Community JSON formats
Basic Format
The basic format is simple, with some more complex extensions discussed at the bottom:
Community JSON format
{
// Basic system parameters:
"_id": string, // String representation of MongoDB ObjectId
"created": string, // Java date format, time when community was created
"modified": string, // Java date format, time when community details were last changed
// Advanced system parameters:
"communityStatus": string, // "active", "disabled", or "pending" (awaiting admin approval)
"isSystemCommunity": boolean, // true for the one system community each cluster has (that every member joins by default)
"isPersonalCommunity": boolean, // Every user also has a personal community, of which only they are a member
"parentId": string, // String representation of MongoDB ObjectId, the "_id" of the parent community, see below.
"parentName": string, // The "name" of the "parent" community, see below.
// Community metadata:
"ownerId": string, // The "_id" field of the community owner (ie the user who created it)
"ownerDisplayName": string, // The above user's "displayName"
"name": string, // The display name of the community
"description": string, // A longer description
"tags": [ string ], // Metadata tags (for future searching applications)
// Member information:
"numberOfMembers": integer,
"members": [{
// From "person" object, see link below
"_id": string,
"email": string,
"displayName": string,
"languages": [ string ],
"contacts": [ {...} ], // The same format as for the "person" object
"links": [ {...} ], // The same format as for the "person" object
"userType": string, // One of "member", "content_publisher", "moderator" or "owner" (moderators have the same abilities as the owner; content publishers can create active sources without moderator/owner authorization)
"userStatus": string, // One of "active", "disabled" or "pending" ("pending" means awaiting approval from an owner/moderator - this functionality is not yet implemented)
"userAttributes": [{ // Overrides for the default
"type": string, // This actually maps onto the key from the parent "userAttributes" map, see below
"value": string // The default or overridden value
}]
}],
// Community properties:
"userAttributes": { // This is a list of things that members can do (see below)
"USERPROP1": { // This is a map, ie this format is for USERPROP1, USERPROP2, etc;
"type": string, // "boolean", "string"
"defaultValue": string, // string representation of the default value
"allowOverride": boolean // if "true", users can override the default values; defaults to false
},
//etc
},
"communityAttributes": { // This is a list of community properties (see below)
"COMMPROP1": { // This is a map, ie this format is for COMMPROP1, COMMPROP2, etc;
"type": string, // "boolean", "string"
"value": string
},
//etc
}
}
Field Guide
By default community parent attributes point to the system community, in which case they are ignored (the same as not being present). They can be set to a different community via the community create API call. In that case the "sub-community" shares its Lucene index with the parent community (note this is purely an implementation detail, it makes no fuctional/security). It can be used where there are large numbers of communities, since creating large numbers of Lucene indexes gets inefficient.
Three of the fields in the above format are lists (actually sets) or maps of type/value objects:
- userAttributes: governs what community members can and can't do
- communityAttributes: describes what communities allow (normally in terms of discovery and joining)
- members.userAttributes: overrides of the default community "userAttributes"
members
Most of the "members" object fields are simply copied from the Person object.
Community attributes
The following attributes are currently supported:
- isPublic: If "true", can be seen by anyone (via Social - Community - Get Public); if "false", can only be seen by members and administrators
- type: boolean
- value: "true"/"false"
- usersCanSelfRegister: If "true" (and "isPublic" is also "true"), non-members can attempt to invite themselves to join the community (via Social - Community - Member - Join), note this doesn't guarantee success, see "registrationRequiresApproval"; if "false", only existing members (or admins) can invite non-members (via Social - Community - Member - Invite).
- type: boolean
- value: "true"/"false"
- registrationRequiresApproval: If "true" then any accepted invite (eg including normal invites and "self-invites" by non-members) must be approved by a community moderator (an email with a clickable link to Social - Community - Request Response is sent out).
- type: boolean
- value: "true"/"false"
- usersCanCreateSubCommunities: This is a placemarker for allowing users to create child communities (currently the "parent" of a community is not used for any functionality, so this is a spurious attribute).
- type: boolean
- value: "true"/"false"
User attributes
User attributes are slightly more complicated than community attributes because they are applied to each member when they join and then can sometimes be overridden by the user (or an administrator or a community moderator).
As a result, two object types are needed:
- The community has a global attribute map containing the attribute names, their default values and whether they can be overridden
- Each member has a list of these attributes (as type/values, with the "type" field somewhat confusingly mapping to the attribute name; see below for an example), whether they inherited the default or were overridden.
The following attributes are currently supported (actually none are supported within the current functionality):
- publishLoginToActivityFeed: will determine if the community's activity feed will show a user's login.
- type: boolean
- defaultValue: "true"
- publishCommentsToActivityFeed: will determine if comments made by a user on objects like documents will appear on the community activity feed.
- type: boolean
- defaultValue: "true"
- publishSharingToActivityFeed: will determine whether the community activity feed will be notified when the user shares artifacts (queries, datasets etc).
- type: boolean
- defaultValue: "true"
- publishQueriesToActivityFeed: will determine whether new queries made by a user will be published to the community's activity feed.
- type: boolean
- defaultValue: "true"
- publishCommentsPublicly: if "true", non-members will be able to see comments made on objects like documents.
- type: boolean
- defaultValue: "false"
Examples
The following JSON fragment shows an example of attributes in action:
Community JSON object fragment - attributes in action
{
//...
"members":[
{
"_id" : "4cc945379889a84940870102",
"email" : "jill@ikanow.com",
"displayName" : "Jill1 Smith",
"userType" : "member",
"userStatus" : "active",
"userAttributes" : [
{
"type" : "publishQueriesToActivityFeed",
"value" : "true"
},
{
"type" : "publishCommentsPublicly",
"value" : "false"
},
{
"type" : "publishCommentsToActivityFeed",
"value" : "true"
},
{
"type" : "publishSharingToActivityFeed",
"value" : "true"
},
{
"type" : "publishLoginToActivityFeed",
"value" : "true"
}
]
},
]
//...
"communityAttributes" : {
"isPublic" : {
"type" : "boolean",
"value" : "true"
},
"usersCanSelfRegister" : {
"type" : "boolean",
"value" : "false"
},
"registrationRequiresApproval" : {
"type" : "boolean",
"value" : "false"
},
"usersCanCreateSubCommunities" : {
"type" : "boolean",
"value" : "false"
}
},
"userAttributes" : {
"publishLoginToActivityFeed" : {
"type" : "boolean",
"defaultValue" : "true",
"allowOverride" : false
},
"publishCommentsToActivityFeed" : {
"type" : "boolean",
"defaultValue" : "true",
"allowOverride" : false
},
"publishSharingToActivityFeed" : {
"type" : "boolean",
"defaultValue" : "true",
"allowOverride" : false
},
"publishQueriesToActivityFeed" : {
"type" : "boolean",
"defaultValue" : "true",
"allowOverride" : false
},
"publishCommentsPublicly" : {
"type" : "boolean",
"defaultValue" : "false",
"allowOverride" : false
}
},
//...
}