static osapi.jive.corev3.people
REST endpoint for interacting with Jive users via an API that is compatible with OpenSocial.
Examples:
Perform a GET request to . Here is an example curl command of getting one person by email and retrieving only the "name" field:
curl -u liz.employee:password "http://example.jiveon.com/api/core/v3/people/email/bob@example.com?fields=name"
Perform a GET request to . Here is an example curl command of getting one person by username and retrieving only the "emails" and "name" fields:
curl -u person:password "http://example.jiveon.com/api/core/v3/people/username/joeuser?fields=emails,name"
Perform a POST request to . Here is an example curl command of creating a task for a user with ID 1234:
curl -u user:password -H "Content-Type: application/json" --data
'{ "subject": "Organize teambuilding event", "dueDate": "2012-12-05T06:59:59.999+0000" }' http://example.jiveon.com/api/core/v3/people/1234/tasks
Methods
acceptTermsAndConditions(options)
POST /people/{personID}/acceptTermsAndConditionsRetrieves
ObjectDescription
create(person,options)
POST /peopleRetrieves
PersonDescription
Create a Person for a new user based on the contents of the specified Person. Only modifiable fields that actually provide a value in the incoming entity are processed.
The JSON representation of the absolute minimum information that must be included to create a new person looks like this:
{ "emails" : [ { "value" : "{emailAddress}", "jive_label" : "Email" } ], "jive" : { "password" : "{password}", "username" : "{username}" }, "name" : { "familyName" : "{lastName}", "givenName" : "{firstName}" } }
Takes:
- Person fields describing the new person
Options:
| Name | Type | Required | Description |
|---|---|---|---|
| welcome | Boolean | false | Flag indicating that a welcome email should be sent to the new person (since 3.2) |
| fields | String | false | Names of the fields to be returned |
Retrieves:
get(options)
GET /peopleRetrieves
Person[]Description
Return a paginated list of people that match the specified selection criteria. Note that the
options to filter by company, department, hire-date, location and
office are not always going to be available in all Jive instances. You will have to use
getFilterableFields() to discover the availability of those filters.
This method supports the following values for the sort field.
| Sort | Description |
|---|---|
| firstNameAsc | Sort by first name in ascending order |
| lastNameAsc | Sort by last name in ascending order |
| dateJoinedDesc | Sort by joined date in ascending order |
| dateJoinedAsc | Sort by joined date in descending order |
| statusLevelDesc | Sort by status level in descending order |
Options:
| Name | Type | Required | Description |
|---|---|---|---|
| company | String | false | Company name that must match to select a person |
| count | Integer | false | Maximum number of security groups to return (default is 25) |
| department | String | false | Department that must match to select a person |
| fields | String | false | Names of the fields to be returned |
| hire-date | String | false | Two-element array that contains beginning and ending timestamps defining the range of hire dates a person's hire date must be in to be selected |
| include-disabled | String | false | Flag indicating whether disabled users should be returned in search results |
| location | String | false | Location that must match to select a person |
| office | String | false | Office name that must match to select a person |
| query | String | false | Query string containing keywords that must match to select a person. Wildcards can be used, e.g. to search by substring use "*someSubstring*". |
| sort | String | false | Identifier defining the sort sequence for returned people |
| startIndex | Integer | false | Zero-relative index of the first security group to return (default is 0) |
| tag | String | false | One or more tags that must match to select a person |
| title | String | false | Job title that must match to select a person |
Retrieves:
get(options)
GET /people/email/{email}Retrieves
PersonDescription
Return the specified person by email address.
Options:
| Name | Type | Required | Description |
|---|---|---|---|
| String | true | Email address of the specified person | |
| fields | String | false | Names of the fields to be returned |
Retrieves:
get(options)
GET /people/{uri}Retrieves
PersonDescription
Return the specified person by URI.
Options:
| Name | Type | Required | Description |
|---|---|---|---|
| uri | String | true | URI of the specified person |
| fields | String | false | Names of the fields to be returned |
Retrieves:
get(options)
GET /people/username/{username}Retrieves
PersonDescription
Return the specified person by username.
Options:
| Name | Type | Required | Description |
|---|---|---|---|
| username | String | true | Username of the specified person |
| fields | String | false | Names of the fields to be returned |
Retrieves:
getFilterableFields()
GET /people/@filterableFieldsRetrieves
String[]Description
Return the set of fields that can be used for filtering users in this Jive instance.
getMetadata()
GET /people/@metadataRetrieves
ObjectDescription
Return metadata about our data object type in this Jive instance
getRecommendedPeople(options)
GET /people/recommendedRetrieves
Person[]Description
Return a list of recommended people. Use getPropertyMetadata({name:'feature.recommender.enabled'}) to figure out whether recommendation service is enabled or not.
Options:
| Name | Type | Required | Description |
|---|---|---|---|
| count | Integer | false | Maximum number of security groups to return (default is 25) |
| fields | String | false | Names of the fields to be returned |
Retrieves:
Since: 3.1
getResources()
GET /people/@resourcesRetrieves
Resource[]Description
Return metadata about the resources available for our data object type in this Jive instance.
getSupportedFields()
GET /people/@supportedFieldsRetrieves
String[]Description
Return the set of fields for our object type that are supported in this Jive instance.
getTrendingPeople(options)
GET /people/trendingRetrieves
Person[]Description
Return a list of trending people that match the specified selection filter criteria. Use getPropertyMetadata({name:'feature.recommender.enabled'}) to figure out whether recommendation service is enabled or not.
Options:
| Name | Type | Required | Description |
|---|---|---|---|
| count | Integer | false | Maximum number of security groups to return (default is 25) |
| fields | String | false | Names of the fields to be returned |
| place | String | false | URI of a place, users that are trending in this place |
Retrieves:
Since: 3.1
requestPicker(options)Retrieves
ObjectDescription
Request the Jive container to prompt the user to select either a single person, or a group of people,
based on the state of the multiple option. When the user has done so, the
success callback will be called, passing in either:
- If
multipleisfalse, or exactly one person was selected, the data will be the Person object representing the selected person - If more than one Person was selected, the data will be a normal list result with a
listfield containing the actual Person objects
If the user closes the picker without selecting any people, no callback will occur. An example call:
osapi.jive.corev3.people.requestPicker({ multiple : false, success : function(data) { // "data" will be the Person object selected by the user } };
Availability:
Available only within a Jive App that has included the jive-core-v3 feature.
Options:
| Name | Type | Required | Description |
|---|---|---|---|
| multiple | Boolean | false | Flag indicating whether the user is allowed to select multiple people or not (default is false) |
| error | Function | false | Callback function that will be called if an error occurs. Passed data object will
include a message field containing the error message. |
| success | Function | false | Callback function that will be called if the user successfully selects a place. Passed data object will be the place object for that place, including all of the instance methods |
search(options)
GET /search/peopleRetrieves
Person[]Description
Search for and return people that match the specified filter criteria.
Options:
| Name | Type | Required | Description |
|---|---|---|---|
| count | Integer | false | Maximum number of results to be returned |
| fields | String | false | Names of the fields to be returned |
| nameonly | String | false | Flag indicating whether to limit search results to only people that match by name (Defaults to false) |
| search | String | false | One or more search terms, separated by commas. You must escape any of the following special characters embedded in the search terms: comma (","), backslash ("\"), left parenthesis ("("), and right parenthesis(")"), by preceding them with a backslash. Wildcards can be used, e.g. to search by substring use "*someSubstring*". |
| startIndex | Integer | false | Zero-relative index of the first result to be returned |