jive-sdk
Version:
Node.js SDK for Jive Software to assist with the development of add-ons
2,023 lines (745 loc) • 28.6 kB
HTML
<html lang="en">
<head>
<meta charset="utf-8">
<title>Jive SDK Module: community</title>
<!--[if lt IE 9]>
<script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
<link type="text/css" rel="stylesheet" href="styles/sunlight.default.css">
<link type="text/css" rel="stylesheet" href="styles/site.spacelab.css">
</head>
<body>
<div class="container-fluid">
<div class="navbar navbar-fixed-top navbar-inverse">
<div class="navbar-inner">
<a class="brand" href="index.html">Jive SDK</a>
<ul class="nav">
<li class="dropdown">
<a href="modules.list.html" class="dropdown-toggle" data-toggle="dropdown">Modules<b
class="caret"></b></a>
<ul class="dropdown-menu ">
<li>
<a href="module-abstractDefinitions.html">abstractDefinitions</a>
</li>
<li>
<a href="module-abstractInstances.html">abstractInstances</a>
</li>
<li>
<a href="module-addOnRoutes.html">addOnRoutes</a>
</li>
<li>
<a href="module-api.html">api</a>
</li>
<li>
<a href="module-community.html">community</a>
</li>
<li>
<a href="module-constants.html">constants</a>
</li>
<li>
<a href="module-devRoutes.html">devRoutes</a>
</li>
<li>
<a href="module-events.html">events</a>
</li>
<li>
<a href="module-extensions.html">extensions</a>
</li>
<li>
<a href="module-extstreamsInstances.html">extstreamsInstances</a>
</li>
<li>
<a href="module-jiveutil.html">jiveutil</a>
</li>
<li>
<a href="module-oauthRoutes.html">oauthRoutes</a>
</li>
<li>
<a href="module-request.html">request</a>
</li>
<li>
<a href="module-security.html">security</a>
</li>
<li>
<a href="module-service.html">service</a>
</li>
<li>
<a href="module-tasks.html">tasks</a>
</li>
<li>
<a href="module-tileInstances.html">tileInstances</a>
</li>
<li>
<a href="module-tileRoutes.html">tileRoutes</a>
</li>
<li>
<a href="module-tilesDefinitions.html">tilesDefinitions</a>
</li>
<li>
<a href="module-webhooks.html">webhooks</a>
</li>
</ul>
</li>
<li class="dropdown">
<a href="classes.list.html" class="dropdown-toggle" data-toggle="dropdown">Classes<b
class="caret"></b></a>
<ul class="dropdown-menu ">
<li>
<a href="extstreamsDefinitions.html">extstreamsDefinitions</a>
</li>
<li>
<a href="filePersistence.html">filePersistence</a>
</li>
<li>
<a href="memoryPersistence.html">memoryPersistence</a>
</li>
<li>
<a href="memoryScheduler.html">memoryScheduler</a>
</li>
<li>
<a href="oauthHandler.html">oauthHandler</a>
</li>
</ul>
</li>
</ul>
</div>
</div>
<div class="row-fluid">
<div class="span8">
<div id="main">
<h1 class="page-title">Module: community</h1>
<section>
<header>
<h2>
community
</h2>
</header>
<article>
<div class="container-overview">
<div class="description"><p>API for interacting with Jive communities.</p></div>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="community.js.html">jive-sdk-api/lib/community/community.js</a>, <a href="community.js.html#sunlight-1-line-18">line 18</a>
</li></ul></dd>
</dl>
</div>
<h3 class="subsection-title">Methods</h3>
<dl>
<dt>
<h4 class="name" id="doRequest"><span class="type-signature"><static> </span>doRequest<span class="signature">(community, options)</span><span class="type-signature"> → {Promise}</span></h4>
</dt>
<dd>
<div class="description">
<p>Make a request to the current community.
Automatically handle access token refresh flow if failure.</p>
</div>
<h5>Parameters:</h5>
<table class="params table table-striped">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>community</code></td>
<td class="type">
</td>
<td class="description last"></td>
</tr>
<tr>
<td class="name"><code>options</code></td>
<td class="type">
<span class="param-type">Object</span>
</td>
<td class="description last"><p>Request options.</p>
<h6>Properties</h6>
<table class="params table table-striped">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>path</code></td>
<td class="type">
<span class="param-type">String</span>
</td>
<td class="description last"><p>Path relative to given community's jiveURL; used if options.url doesn't exist.</p></td>
</tr>
<tr>
<td class="name"><code>url</code></td>
<td class="type">
<span class="param-type">String</span>
</td>
<td class="description last"><p>Full request URL. options.path is not used if options.url is provided.</p></td>
</tr>
<tr>
<td class="name"><code>headers</code></td>
<td class="type">
<span class="param-type">Object</span>
</td>
<td class="description last"><p>Map of header key-values.</p></td>
</tr>
<tr>
<td class="name"><code>oauth</code></td>
<td class="type">
<span class="param-type">Object</span>
</td>
<td class="description last"><p>Map of oauth properties.</p>
<h6>Properties</h6>
<table class="params table table-striped">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>access_token</code></td>
<td class="type">
<span class="param-type">String</span>
</td>
<td class="description last"><p>OAuth access token.</p></td>
</tr>
<tr>
<td class="name"><code>refresh_token</code></td>
<td class="type">
<span class="param-type">String</span>
</td>
<td class="description last"><p>OAuth refresh token.</p></td>
</tr>
</tbody>
</table>
</td>
</tr>
<tr>
<td class="name"><code>tokenPersistenceFunction</code></td>
<td class="type">
<span class="param-type">function</span>
</td>
<td class="description last"><p>Callback function that will be invoked with new oauth access and refresh
tokens ({'access_token' : '...', 'refresh_token' : '...' }). If not provided, the community will be updated with the new access tokens.</p></td>
</tr>
</tbody>
</table>
</td>
</tr>
</tbody>
</table>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="community.js.html">jive-sdk-api/lib/community/community.js</a>, <a href="community.js.html#sunlight-1-line-226">line 226</a>
</li></ul></dd>
</dl>
<h5>Returns:</h5>
<div class="param-desc">
<p>Promise</p>
</div>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">Promise</span>
</dd>
</dl>
</dd>
<dt>
<h4 class="name" id="find"><span class="type-signature"><static> </span>find<span class="signature">(filter)</span><span class="type-signature"> → {Promise}</span></h4>
</dt>
<dd>
<div class="description">
<p>Searches persistence for communities that matches the given criteria filter object.</p>
</div>
<h5>Parameters:</h5>
<table class="params table table-striped">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>filter</code></td>
<td class="type">
</td>
<td class="description last"></td>
</tr>
</tbody>
</table>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="community.js.html">jive-sdk-api/lib/community/community.js</a>, <a href="community.js.html#sunlight-1-line-71">line 71</a>
</li></ul></dd>
</dl>
<h5>Returns:</h5>
<div class="param-desc">
<p>Promise</p>
</div>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">Promise</span>
</dd>
</dl>
</dd>
<dt>
<h4 class="name" id="findByCommunity"><span class="type-signature"><static> </span>findByCommunity<span class="signature">(jiveCommunity)</span><span class="type-signature"> → {Promise}</span></h4>
</dt>
<dd>
<div class="description">
<p>Searches persistence for a community that matches the name of the given jive community.
If one is not found, the promise will resolve a null (undefined) value.</p>
</div>
<h5>Parameters:</h5>
<table class="params table table-striped">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>jiveCommunity</code></td>
<td class="type">
</td>
<td class="description last"></td>
</tr>
</tbody>
</table>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="community.js.html">jive-sdk-api/lib/community/community.js</a>, <a href="community.js.html#sunlight-1-line-94">line 94</a>
</li></ul></dd>
</dl>
<h5>Returns:</h5>
<div class="param-desc">
<p>Promise</p>
</div>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">Promise</span>
</dd>
</dl>
</dd>
<dt>
<h4 class="name" id="findByJiveURL"><span class="type-signature"><static> </span>findByJiveURL<span class="signature">(jiveUrl)</span><span class="type-signature"> → {Promise}</span></h4>
</dt>
<dd>
<div class="description">
<p>Searches persistence for community that matches the given jiveUrl.
If one is not fond,
the promise will resolve with a null (undefined) value.</p>
</div>
<h5>Parameters:</h5>
<table class="params table table-striped">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>jiveUrl</code></td>
<td class="type">
</td>
<td class="description last"></td>
</tr>
</tbody>
</table>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="community.js.html">jive-sdk-api/lib/community/community.js</a>, <a href="community.js.html#sunlight-1-line-82">line 82</a>
</li></ul></dd>
</dl>
<h5>Returns:</h5>
<div class="param-desc">
<p>Promise</p>
</div>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">Promise</span>
</dd>
</dl>
</dd>
<dt>
<h4 class="name" id="findByTenantID"><span class="type-signature"><static> </span>findByTenantID<span class="signature">(tenantID)</span><span class="type-signature"> → {Promise}</span></h4>
</dt>
<dd>
<div class="description">
<p>Searches persistence for a community that matches the tenantID of the given jive community.
If one is not found, the promise will resovle a null (undefined) value.</p>
</div>
<h5>Parameters:</h5>
<table class="params table table-striped">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>tenantID</code></td>
<td class="type">
</td>
<td class="description last"></td>
</tr>
</tbody>
</table>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="community.js.html">jive-sdk-api/lib/community/community.js</a>, <a href="community.js.html#sunlight-1-line-106">line 106</a>
</li></ul></dd>
</dl>
<h5>Returns:</h5>
<div class="param-desc">
<p>Promise</p>
</div>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">Promise</span>
</dd>
</dl>
</dd>
<dt>
<h4 class="name" id="parseJiveCommunity"><span class="type-signature"><static> </span>parseJiveCommunity<span class="signature">(jiveUrl)</span><span class="type-signature"></span></h4>
</dt>
<dd>
<div class="description">
<p>Parses the given jiveUrl for the name of the community.</p>
</div>
<h5>Parameters:</h5>
<table class="params table table-striped">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>jiveUrl</code></td>
<td class="type">
</td>
<td class="description last"></td>
</tr>
</tbody>
</table>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="community.js.html">jive-sdk-api/lib/community/community.js</a>, <a href="community.js.html#sunlight-1-line-117">line 117</a>
</li></ul></dd>
</dl>
<h5>Returns:</h5>
<div class="param-desc">
<p>Name of the community based on the jiveUrl.</p>
</div>
</dd>
<dt>
<h4 class="name" id="register"><span class="type-signature"><static> </span>register<span class="signature">(registration, registration)</span><span class="type-signature"> → {Promise}</span></h4>
</dt>
<dd>
<div class="description">
<p>Processes the incoming community addon registration request object.
Validation rules:<br></p>
<ul>
<li>If jive.context.config['development'] == true, addon registration validation will be skipped.</li>
<li>If not, then registration.jiveSignatureURL will be invoked to validate the registration block.
Failure will cause the return promise reject callback to be fired.</li>
</ul>
<p>Upon successful registration, a community object will be persisted or updated (if one already exists) based on the
contents of the registration object.</p>
</div>
<h5>Parameters:</h5>
<table class="params table table-striped">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>registration</code></td>
<td class="type">
<span class="param-type">Object</span>
</td>
<td class="description last"><p>Community addon registration object.</p>
<h6>Properties</h6>
<table class="params table table-striped">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>jiveSignature</code></td>
<td class="type">
<span class="param-type">String</span>
</td>
<td class="description last"><p>Signature provided by Jive used for registration validation.</p></td>
</tr>
<tr>
<td class="name"><code>clientSecret</code></td>
<td class="type">
<span class="param-type">String</span>
</td>
<td class="description last"><p>Secret provided by the addon service.</p></td>
</tr>
<tr>
<td class="name"><code>jiveSignatureURL</code></td>
<td class="type">
<span class="param-type">String</span>
</td>
<td class="description last"><p>URL used for validating the registration.</p></td>
</tr>
<tr>
<td class="name"><code>jiveUrl</code></td>
<td class="type">
<span class="param-type">String</span>
</td>
<td class="description last"><p>URL of the originating Jive community.</p></td>
</tr>
<tr>
<td class="name"><code>tenantId</code></td>
<td class="type">
<span class="param-type">String</span>
</td>
<td class="description last"><p>Tenant ID of the originating Jive community. This is a durable, global ID.</p></td>
</tr>
<tr>
<td class="name"><code>clientId</code></td>
<td class="type">
<span class="param-type">String</span>
</td>
<td class="description last"><p>Client ID assigned by the Jive community to the addon as part of this registration request.</p></td>
</tr>
<tr>
<td class="name"><code>clientSecret</code></td>
<td class="type">
<span class="param-type">String</span>
</td>
<td class="description last"><p>Client Secret assigned by the Jive community to the addon as part of this registration request.</p></td>
</tr>
<tr>
<td class="name"><code>authorizationCode</code></td>
<td class="type">
<span class="param-type">String</span>
</td>
<td class="description last"><p>Optional. If provided, the system will automatically attempt an OAuth2
access and refresh token exchange with the originating Jive community using this authorization code. The code will be
persisted along with the community object associated with this registration call.</p></td>
</tr>
</tbody>
</table>
</td>
</tr>
<tr>
<td class="name"><code>registration</code></td>
<td class="type">
</td>
<td class="description last"></td>
</tr>
</tbody>
</table>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="community.js.html">jive-sdk-api/lib/community/community.js</a>, <a href="community.js.html#sunlight-1-line-364">line 364</a>
</li></ul></dd>
</dl>
<h5>Returns:</h5>
<div class="param-desc">
<p>Promise</p>
</div>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">Promise</span>
</dd>
</dl>
</dd>
<dt>
<h4 class="name" id="requestAccessToken"><span class="type-signature"><static> </span>requestAccessToken<span class="signature">(jiveUrl, oauthCode)</span><span class="type-signature"> → {Promise}</span></h4>
</dt>
<dd>
<div class="description">
<p>Requests an access token by oauth access code (oauth access code is given in registration requests and valid for few minutes).</p>
</div>
<h5>Parameters:</h5>
<table class="params table table-striped">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>jiveUrl</code></td>
<td class="type">
</td>
<td class="description last"><p>the url of the jive community. this function will use this url to find the community in the persistence and get the client id and secret.</p></td>
</tr>
<tr>
<td class="name"><code>oauthCode</code></td>
<td class="type">
</td>
<td class="description last"><p>the code needed to be use to get access to a specific registration scope (usually a group).</p></td>
</tr>
</tbody>
</table>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="community.js.html">jive-sdk-api/lib/community/community.js</a>, <a href="community.js.html#sunlight-1-line-128">line 128</a>
</li></ul></dd>
</dl>
<h5>Returns:</h5>
<div class="param-desc">
<p>Promise A promise for success and failure [use .then(...) and .catch(...)]</p>
</div>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">Promise</span>
</dd>
</dl>
</dd>
<dt>
<h4 class="name" id="save"><span class="type-signature"><static> </span>save<span class="signature">(community)</span><span class="type-signature"> → {Promise}</span></h4>
</dt>
<dd>
<div class="description">
<p>Saves the given community object into persistence. Will throw an Error if the community object
does not contain a 'jiveUrl' property.</p>
</div>
<h5>Parameters:</h5>
<table class="params table table-striped">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>community</code></td>
<td class="type">
<span class="param-type">Object</span>
</td>
<td class="description last"><p>Community object, which must specify a jiveUrl property at minimum.</p></td>
</tr>
</tbody>
</table>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="community.js.html">jive-sdk-api/lib/community/community.js</a>, <a href="community.js.html#sunlight-1-line-45">line 45</a>
</li></ul></dd>
</dl>
<h5>Returns:</h5>
<div class="param-desc">
<p>Promise</p>
</div>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">Promise</span>
</dd>
</dl>
</dd>
</dl>
</article>
</section>
</div>
<div class="clearfix"></div>
<footer>
<span class="copyright">
Jive Software, Inc
</span>
<br />
<span class="jsdoc-message">
Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.3.0-dev</a>
on Wed Jan 22 2014 12:29:38 GMT-0800 (PST) using the <a href="https://github.com/terryweiss/docstrap">DocStrap template</a>.
</span>
</footer>
</div>
<div class="span3">
<div id="toc"></div>
</div>
<br clear="both">
</div>
</div>
<script src="scripts/sunlight.js"></script>
<script src="scripts/sunlight.javascript.js"></script>
<script src="scripts/sunlight-plugin.doclinks.js"></script>
<script src="scripts/sunlight-plugin.linenumbers.js"></script>
<script src="scripts/sunlight-plugin.menu.js"></script>
<script src="scripts/jquery.min.js"></script>
<script src="scripts/jquery.scrollTo.js"></script>
<script src="scripts/jquery.localScroll.js"></script>
<script src="scripts/bootstrap-dropdown.js"></script>
<script src="scripts/toc.js"></script>
<script> Sunlight.highlightAll({lineNumbers:true, showMenu: true, enableDoclinks :true}); </script>
<script>
$( function () {
$( "#toc" ).toc( {
selectors : "h1,h2,h3,h4",
showAndHide : false,
scrollTo : 60
} );
$( "#toc>ul" ).addClass( "nav nav-pills nav-stacked" );
$( "#main span[id^='toc']" ).addClass( "toc-shim" );
} );
</script>
</body>
</html>