JavaScript Bridge API and BTCA files

Introduction

The purpose of the JavaScript Bridge API is to allow users to create BTCA files that can request data or perform actions in the Hub.

Important Changes from 2.0

JavaScript Bridge 3.0 brings support to Web App. Some actions have been removed and responses have been modified in order to provide support to all platforms. JavaScript Bridge 2.0 support will be phased out in the future. Documentation is available here.

What are BTCA files?

BTCA files are sandboxed HTML5 applications. A regular XMLHttpRequest is not permitted to run when a BTCA file is loaded in the Hub. All requests must make use of the JavaScript Bridge API, see below for usage instructions.

Usage

The recommended method of interacting with the JavaScript Bridge is to include btca-client in your project. See BTCA Client Library for usage instructions.


Actions

Below is a list of actions and available parameters. Parameters prefixed with an asterisk (*) are required.

Parameter defaults

Some parameters have a global default. These are not required to be passed when sending an action.

{
  limit:  5,  // Number of results, maximum is 100
  offset: 0   // Offset of results, used for pagination
}

addInterestArea

Add or remove Interest Area assigned to the current user’s account.

removeInterestArea should be set as the action if you wish to remove. id can be retrieved with getInterestAreas.

Parameters

{
  id:       *Integer   // Interest Area id
}

Errors

Version Support

PlatformAvailability
Android
iOS5.1.1
Web5.0 Beta 10
Windows

closeFileViewer

Close the current active file or all files in the File Viewer.

Parameters

{
  option:       *String    // 'all' or 'currentTab'
}

Errors

Version Support

PlatformAvailability
Android
iOS5.1.1
Web5.0 Beta 10
Windows

cloudFilesProxy

Query supported Cloudfiles services. Note: All other parameters not specified below will be set as query parameters on a GET request.

Parameters

{
  url:       *String,
  method:    *String,   // GET, POST, PATCH, DELETE
  source:    *String,   // dynamics, salesforce
  body:      Object,    // key/value pairs sent as JSON (POST/PATCH only)
  headers:   Array      // Array of key/value pairs to set to request header
}

Errors

Version Support

PlatformAvailability
Android
iOS
Web5.0 Beta 12
Windows

createComment

Create a new comment on a Story.

Parameters

{
  storyId:       *Number,
  message:       *String
}

Errors

Version Support

PlatformAvailability
Android
iOS5.1.1
Web5.0 Beta 10
Windows

createCommentReply

Reply to a comment on a Story.

Parameters

{
  commentId:     *Number,
  message:       *String
}

Errors

Version Support

PlatformAvailability
Android
iOS5.1.1
Web5.0 Beta 10
Windows

createStory

A Story can be created programmatically or the user can be redirected to the Create Story UI by setting visual. On iOS, new Stories are created as drafts and will be sent to the server in the next synchronisation cycle which occurs every 30 seconds. The request also allows a temporary file to be attached if fileData, fileExt and fileName are provided. Note that attaching files is not supported on Web. If creating a Story with expiryTimeStamp, you must also set a valid expiryTimeStampTz. See List of tz database time zones.

Parameters

{
  channelId:            *Integer    // Primary Channel ID
  title:                *String,    // Story title
  description:          String,     // Story message description
  excerpt:              String,     // Story message excerpt
  expiryTimeStamp:      Integer     // Unix timestamp
  expiryTimeStampTz:    String,     // Timezone string, e.g. 'Australia/Sydney' (not supported on device)
  fileData:             String,     // Required if fileExt or fileName exists
  fileExt:              String,     // Required if fileData or fileName exists
  fileName:             String,     // Required if fileData or fileExt exists
  notify:               Boolean,    // Enable device notifications
  visual:               Boolean     // Show Create Story UI with pre-filled data
}

Response

  id:         Integer         // Story ID if created on the server, otherwise set to null
  isPending:  Boolean         // Server pending status

Errors

Version Support

PlatformAvailability
Android
iOS5.1.1
Web5.0 Beta 10
Windows

editStory

Functions in the same way as createStory, requires a storyId to be passed.

Parameters

{
  storyId:              *Integer,   // Story ID
  channelId:            *Integer,   // Primary Channel ID
  title:                String,     // Story title
  description:          String,     // Story message description
  excerpt:              String,     // Story message excerpt
  expiryTimeStamp:      Integer,    // Unix timestamp
  expiryTimeStampTz:    String,     // Timezone string, e.g. 'Australia/Sydney' (not supported on device)
  fileData:             String,     // Required if fileExt or fileName exists
  fileExt:              String,     // Required if fileData or fileName exists
  fileName:             String,     // Required if fileData or fileExt exists
  notify:               Boolean,    // Enable device notifications
  visual:               Boolean     // Show Create Story UI with pre-filled data
}

Errors

Version Support

PlatformAvailability
Android
iOS5.1.1
Web5.0 Beta 10
Windows

editUserProfile

Navigates to the User Edit Profile view.

Errors

Version Support

PlatformAvailability
Android
iOS5.1.1
Web5.0 Beta 10
Windows

followUser

unfollowUser should be set as the action if you wish to unfollow.

Parameters

{
  userId:   *Number
}

Response

{
  id:         Integer,        // User ID
  isFollowed: Boolean         // Follow status of user
}

Errors

Version Support

PlatformAvailability
Android
iOS5.1.1
Web5.0 Beta 10
Windows

getBookmarkList

Returns an array of bookmark data.

Parameters

{
  entityName:       *String,    // name of entity (story, fileCollection)
  offset:           Integer,    // offset for pagination
  limit:            Integer,    // number of results
  sortBy:           String      // valid [entity sort attribute](#sortBy-table)
}

Errors

Version Support

PlatformAvailability
Android
iOS5.1.1
Web5.0 Beta 10
Windows

getCluiCourseURL

Returns a CLUI course URL. Company must be enabled for LMS.

Parameters

{
  id:       *Integer   // CLUI course id
}

Response

{
  url:       String   // CLUI course URL
}

Errors

Version Support

PlatformAvailability
Android
iOS5.1.1
Web5.0 Beta 10
Windows

getDraftList

Returns an array of draft Stories.

Parameters

{
  offset:           Integer,    // offset for pagination
  limit:            Integer,    // number of results
  sortBy:           String      // [entity sort attribute](#sortBy-table)
}

Errors

Version Support

PlatformAvailability
Android
iOS5.1.1
Web-
Windows

getEntity

Returns a full record of the requested entity. See Entities> for expected response.

Parameters

{
  entityName:   *String,     // file, story, user
  id:           *Integer     // id of entity
}

Errors

Version Support

PlatformAvailability
Android
iOS5.1.1
Web5.0 Beta 10
Windows

getInterestAreas

Returns an array of available Interest Areas. Use addInterestArea to subscribe.

Version Support

PlatformAvailability
Android
iOS5.1.1
Web5.0 Beta 10
Windows

getList

Returns an array of entities. Optionally pass parentEntityName and peid to return entities associated with a parent.

Parameters

{
  entityName:       *String,    // name of entity (tab, channel, story, file, user)
  parentEntityName: String,     // name of parent entity, required with `peid`
  peid:             Integer,    // parent entity id, required with `parentEntityName`
  offset:           Integer,    // offset for pagination
  limit:            Integer,    // number of results
  createDateSince   Integer,    // (only story entity supported) - return stories with revision dates within Since & To dates
  createDateTo      Integer,    // (only story entity supported) - return stories with revision dates within Since & To dates
  sortBy:           String      // valid [entity sort attribute](#sortBy-table)
}

Supported Parent Entities

EntityParent Entity
channeltab
storychannel or tab
filestory

Supported sortBy Attributes

Defaults are in bold.

EntitysortBy
tabchannelCount, name
channelname, storyCount
storycreateDate, title, likesCount, authorFirstName, authorLastName
userfirstName, lastName, score
filecreateDate, description, size
fileCollectioncreateDate, name

Errors

Version Support

PlatformAvailability
Android
iOS5.1.1
Web5.0 Beta 10
Windows

getLocation

Returns the current geolocation data.

Response

{
  lat:                  Integer,  // latitude, -180 if unavailable
  long:                 Integer,  // longitude, -180 if unavailable
  lastUpdatedTimestamp: Integer   // unix timestamp
}

Version Support

PlatformAvailability
Android
iOS5.1.1
Web5.0 Beta 10
Windows

getNewList

Returns an array of entities sorted by date.

Parameters

{
  entityName:       *String,    // name of entity (story)
  offset:           Integer,    // offset for pagination
  limit:            Integer     // number of results
}

Errors

Version Support

PlatformAvailability
Android
iOS5.1.1
Web5.0 Beta 10
Windows

getRecommendedList

Returns an array of recommended entities.

Parameters

{
  entityName:       *String,    // name of entity (file, story, file)
  offset:           Integer,    // offset for pagination
  limit:            Integer     // number of results
}

Errors

Version Support

PlatformAvailability
Android
iOS5.1.1
Web5.0 Beta 10
Windows

getSystemConfig

Returns information about the current Hub instance.

Parameters

{
  appName:              String,       // Name of app (Hub Web App, Hub for Android, Hub for iOS, Hub for Windows)
  appVersion:           String,       // Version of app
  bridgeVersion:        String,       // Version of JavaScript Bridge
  mainThemeHexColor:    String,       // Hex value of company base color
  serverURL:            String,       // URL of server
  terminology:          Object,       // nounPlural, nounSinglar objects with tab, channel, story string values
  userId:               Integer       // ID of current user
}

Version Support

PlatformAvailability
Android
iOS5.1.1
Web5.0 Beta 10
Windows

likeStory

unlikeStory should be set as the action if you wish to unlike.

Parameters

{
  storyId:   *Integer
}

Response

{
  id:         Integer,        // Story ID
  isLiked:    Boolean         // Like status of Story
}

Errors

Version Support

PlatformAvailability
Android
iOS5.1.1
Web5.0 Beta 10
Windows

openEntity

Navigates to the specified entity UI.

Parameters

{
  entityName:   *String,  // tab, channel, story, file, fileCollection, user (device support below)
  id:           *Integer  // id of specified entity
}

Entity Support

EntityPlatforms
tabWeb
channel
storyWeb
file
fileCollection
userWeb

Errors

Version Support

PlatformAvailability
Android
iOS5.1.1
Web5.0 Beta 10
Windows

openInterestAreas

Navigates to or displays the Interest Areas view.

Version Support

PlatformAvailability
Android
iOS5.1.1
Web5.0 Beta 10
Windows

openMenu

Navigate to the specified menuType.

Parameters

{
  menuType:   *String   // chat, company, content, me, meetings, notes, notifications
}

Errors

Version Support

PlatformAvailability
Android
iOS5.1.1
Web5.0 Beta 10
Windows

openURL

Opens the URL in the File Viewer on devices or a new browser tab on Web App.

Parameters

{
  url:   *String    // Valid URL
}

Errors

Version Support

PlatformAvailability
Android
iOS5.1.1
Web5.0 Beta 10
Windows

proxyRequest

Perform a request to a custom end-point. All other parameters not specified below will be set as query parameters on a GET request. Note: It is not possible to target the current Hub API server. These APIs are subject to change at any time, their usage is not recommended or supported.

Parameters

{
  url:       *String,
  method:    *String,   // GET, POST, PATCH, PUT, DELETE
  body:      Object,    // key/value pairs sent as JSON (POST/PATCH/PUT only)
  data:      Object,    // key/value pairs to be sent as FormData (POST/PATCH/PUT only)
  headers:   Array      // Array of key/value pairs to set to request header
}

Errors

Version Support

PlatformAvailability
Android
iOS5.1.1
Web5.0 Beta 12
Windows

search

Navigates to the Search view and performs a search with the assigned keywords.

Parameters

{
  keywords:   *String
}

Errors

Version Support

PlatformAvailability
Android
iOS5.1.1
Web5.0 Beta 10
Windows

searchResult

Returns results of a search. Note that comment and event return full object attributes.

Parameters

{
  keywords:   *String,
  limit:      Integer,    // number of results
  offset:     Integer     // for pagination
}

Response

  comments:   Array,    // [comment](#comment) entities
  feeds:      Array,    // [story](#story) entities
  files:      Array,    // [files](#files) entities
  events:     Array,    // [event](#event) entities
  users:      Array,    // [users](#users) entities
  stories:    Array     // [story](#story) entities

Errors

Version Support

PlatformAvailability
Android
iOS5.1.1
Web5.0 Beta 10
Windows

sendEmail

Present the platform’s default email composer with pre-filled data.

Parameters

{
  to:       *String,      // Email addresses separated by commas
  cc:       String,       // Email addresses separated by commas
  bcc:      String,       // Email addresses separated by commas
  subject:  String,       // Email subject
  body:     String        // Email body
}

Version Support

PlatformAvailability
Android
iOS5.1.1
Web5.0 Beta 10
Windows

subscribeStory

unsubscribeStory should be set as the action if you wish to unsubscribe.

Parameters

{
  storyId:   *Integer
}

Response

{
  id:           Integer,        // Story ID
  isSubscribed: Boolean         // Subscribed status of Story
}

Errors

Version Support

PlatformAvailability
Android
iOS5.1.1
Web5.0 Beta 10
Windows

switchAccount

Force quitting all running process and direct user to switch account UI.

Version Support

PlatformAvailability
Android
iOS5.1.1
Web
Windows

Entities

See below for the expected response for each entity type. Each entity has a “partial” and “full” object. Full objects are returned in getEntity. Partial objects are returned elsewhere unless specified otherwise. Attributes that are part of the full entity response are prefixed below with a question mark (?).

Tab

{
  channelCount: Integer*,                // Total number of Channels
  channels:     ?Array,                  // List of Channels
  id:           Integer,                 // Unique identifier
  isPersonal:   Boolean,                 // Previously type = 1
  isShared:     Boolean,                 // Previously type = 2
  name:         String*,                 // Tab name
  thumbnail:    String,                  // Path to thumbnail
  type:         String = 'tab';          // Static value
}

Channel

{
  defaultSortBy: String,                 // Default Story sorting attribute
  description:   String,                 // Channel description
  id:            Integer,                // Unique identifier
  isFeed:        Boolean,                // Channel contains feed articles
  isHidden:      Boolean,                // Hidden Channel
  isReadable:    Boolean,                // Current user can read this Channel
  isSubscribed:  Boolean,                // Current user is subscribed to this Channel
  isWritable:    Boolean,                // Current user can publish to this Channel
  name:          String,                 // Channel name
  storyCount:    Integer,                // Total number of Stories
  stories:       ?Array,                 // List of Stories
  thumbnail:     String,                 // Path to thumbnail
  type:          String = 'channel'      // Static value
}

Story

{
  author:           ?Object,             // User object of author (Not returned if `isFeed`)
  channel:          ?Object,             // Primary Channel
  commentCount:     Integer,             // Total number of Comments
  comments:         ?Array,              // Comments on Story
  createDate:       Integer,             // Timestamp of Story creation on server
  enableAnnotation: ?Boolean,            // Annotations allowed on Story's files
  events:           ?Array,              // Events related to Story
  excerpt:          String,              // Excerpt of Story message (plain text - not supported on device)
  expiryDate:       Integer,             // Timestamp when Story will be archived by the server
  fileCount:        Integer,             // Total number of Files
  files:            ?Array,              // Files attached to Story
  id:               Integer,             // Unique identifier (Internally referred to as `permId`)
  initialCreateDate Integer,             // Date story was first published in Hub
  isBookmark:       Boolean,             // Current user bookmarked the Story
  isFeed:           Boolean,             // Story is from an RSS feed
  isLiked:          Boolean,             // Current user liked the Story
  isProtected:      Boolean,             // User requires password to access Story. Protected Stories are not saved on device
  isSubscribed:     ?Boolean,            // Current user subscribed to the Story
  isUnread:         Boolean,             // Current user has not read the Story
  likesCount:       Integer,             // Number of Likes
  message:          ?String,             // Story description (normally HTML)
  notify:           ?Boolean,            // Story will send push notifications when updated
  readCount:        ?Integer,            // Total number of time Story opened by users
  quickFileId:      Integer,             // Quickfile ID
  quickFile:        Object,              // File object
  quickLink:        String,              // URL of Quicklink
  sequence:         ?Integer,            // Priority of Story, use for sorting by priority
  sharingType:      ?Integer,            // Sharing Type bit mask value, refers to: email, server, facebook, twitter, linkedIn
  socialURL:        ?String,             // Link of the public URL for sharing
  subscribers:      ?Array,              // List of subscribers
  tags:             ?Array,              // List of tags
  thumbnail:        String,              // Path to thumbnail
  title:            String,              // Story title
  type:             String = 'story'     // Static value
}

Comment

{
  author:     Object,                    // User object of author
  comments:   Array,                     // List of comment replies
  createDate: Integer,                   // Timestamp of Comment creation on server
  id:         Integer,                   // Unique identifier
  isPending:  Boolean,                   // Pending state for syncing to server
  message:    String,                    // Comment content
  story:      ?Object,                   // Related Story (included in searchResult)
  type:       String = 'comment'         // Static value
}

Event

{
  endDate:   Integer,                    // Timestamp of Event end date
  startDate: Integer,                    // Timestamp of Event start date
  id:        Integer,                    // Unique identifier
  name:      String,                     // Name of Event
  story:     ?Object,                    // Related Story (included in searchResult)
  timezone:  String,                     // Timezone string, e.g. 'Australia/Sydney' (not supported on device)
  type:      String = 'event'            // Static value
}

File

{
  category:      String,                 // Category of file (image, video etc.)
  createDate:    Integer,                // Timestamp of creation on server
  description:   String,                 // File description
  downloadURL:   String,                 // URL to download file (only on Web)
  editedLocally: Boolean,                // File has been edited locally
  filename:      String,                 // File name
  id:            Integer,                // Unique identifier
  isDownloaded   Boolean,                // File has been downloaded to device. Web: Returns `null`
  sharingType:   Integer,                // sharingType: 0/1/2 (blocked, optional, mandatory). Android: Fixed value `mandatory`
  size:          Integer,                // Size of the file in bytes
  story:         ?Object,                // Related Story
  thumbnail:     String,                 // Path to thumbnail
  type:          String = 'file',        // Static value
  url:           ?String                  // URL to view file
}

File Collection

{
  createDate: Integer,                   // Timestamp of creation on server
  id:         Integer,                   // Unique identifier
  files:      Array,                     // List of Files
  name:       String,                    // Collection name
  type:       String = 'fileCollection'  // Static value
}

User

{
  badgeColour:       String,             // Hex color of badge
  badgeTitle:        String,             // Badge title
  email:             String,             // Email address
  firstName:         String,             // First name
  followers:         ?Array,             // Followers of the current User
  following:         ?Array,             // Users the current User is following
  groups:            ?Array,             // Groups the user is in
  id:                Integer,            // Unique identifier
  lastName:          String,             // Last name
  score:             Number,             // User score
  subscribedStories: ?Array,             // Stories the currrent User is subscribed to
  thumbnail:         String,             // Path to thumbnail
  title:             String,             // Title set by User
  type:              String = 'user'     // Static value
}

Group

Only returned by getEntity (user).

{
  groupType:  String,                     // ...
  id:         Integer,                    // Unique identifier
  title:      String,                     // Group title
  type:       String = 'group',           // Static value
  users:      ?Array                      // List of users
}

Interest Area

Only returned by getInterestAreas.

{
  colour:       String,                   // Hex colour
  id:           Integer,                  // Unique identifier
  isSubscribed: Boolean,                  // Current user is subscribed
  name:         String,                   // Interest Area name
  thumbnail:    String,                   // URL to thumbnail
  type:         String = 'interestArea'   // Static value
}

Errors

Each error response returns a code and message value to assist debugging.

100 - Invalid Request

Syntax error of the URL or invalid action/jsListener.

101 - Missing Parameter

Parameter is missing or empty.

102 - Invalid Parameter

Parameter type or value is invalid.

103 - API Error

External or internal API error is passed through.

Response

{
  code:         Integer,        // Error ID
  message:      String          // Description of error
}