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}/acceptTermsAndConditions

Retrieves

Object

Description

↑
create(person,options)
POST /people

Retrieves

Person

Description

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:
NameTypeRequiredDescription
welcomeBooleanfalseFlag indicating that a welcome email should be sent to the new person (since 3.2)
fieldsStringfalseNames of the fields to be returned
Retrieves:
  • Person describing the newly created person
    • ↑
    get(options)
    GET /people

    Retrieves

    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.

    SortDescription
    firstNameAscSort by first name in ascending order
    lastNameAscSort by last name in ascending order
    dateJoinedDescSort by joined date in ascending order
    dateJoinedAscSort by joined date in descending order
    statusLevelDescSort by status level in descending order
    Options:
    NameTypeRequiredDescription
    companyStringfalseCompany name that must match to select a person
    countIntegerfalseMaximum number of security groups to return (default is 25)
    departmentStringfalseDepartment that must match to select a person
    fieldsStringfalseNames of the fields to be returned
    hire-dateStringfalseTwo-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-disabledStringfalseFlag indicating whether disabled users should be returned in search results
    locationStringfalseLocation that must match to select a person
    officeStringfalseOffice name that must match to select a person
    queryStringfalseQuery string containing keywords that must match to select a person. Wildcards can be used, e.g. to search by substring use "*someSubstring*".
    sortStringfalseIdentifier defining the sort sequence for returned people
    startIndexIntegerfalseZero-relative index of the first security group to return (default is 0)
    tagStringfalseOne or more tags that must match to select a person
    titleStringfalseJob title that must match to select a person
    Retrieves:
  • Person[]
    • ↑
    get(options)
    GET /people/email/{email}

    Retrieves

    Person

    Description

    Return the specified person by email address.

    Options:
    NameTypeRequiredDescription
    emailStringtrueEmail address of the specified person
    fieldsStringfalseNames of the fields to be returned
    Retrieves:
  • Person describing the specified person
    • ↑
    get(options)
    GET /people/external/{identityType}/{identity}

    Retrieves

    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.

    SortDescription
    firstNameAscSort by first name in ascending order
    lastNameAscSort by last name in ascending order
    dateJoinedDescSort by joined date in ascending order
    dateJoinedAscSort by joined date in descending order
    statusLevelDescSort by status level in descending order
    Options:
    NameTypeRequiredDescription
    companyStringfalseCompany name that must match to select a person
    countStringfalseMaximum number of security groups to return (default is 25)
    departmentStringfalseDepartment that must match to select a person
    fieldsStringfalseNames of the fields to be returned
    hire-dateStringfalseTwo-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-disabledStringfalseFlag indicating whether disabled users should be returned in search results
    locationStringfalseLocation that must match to select a person
    officeStringfalseOffice name that must match to select a person
    queryStringfalseQuery string containing keywords that must match to select a person. Wildcards can be used, e.g. to search by substring use "*someSubstring*".
    sortStringfalseIdentifier defining the sort sequence for returned people
    startIndexStringfalseZero-relative index of the first security group to return (default is 0)
    tagStringfalseOne or more tags that must match to select a person
    titleStringfalseJob title that must match to select a person
    Retrieves:
  • Person[]
    • ↑
    get(options)
    GET /people/{uri}

    Retrieves

    Person

    Description

    Return the specified person by URI.

    Options:
    NameTypeRequiredDescription
    uriStringtrueURI of the specified person
    fieldsStringfalseNames of the fields to be returned
    Retrieves:
  • Person describing the specified person
    • ↑
    get(options)
    GET /people/username/{username}

    Retrieves

    Person

    Description

    Return the specified person by username.

    Options:
    NameTypeRequiredDescription
    usernameStringtrueUsername of the specified person
    fieldsStringfalseNames of the fields to be returned
    Retrieves:
  • Person describing the specified person
    • ↑
    getFilterableFields()
    GET /people/@filterableFields

    Retrieves

    String[]

    Description

    Return the set of fields that can be used for filtering users in this Jive instance.

    ↑
    getMetadata()
    GET /people/@metadata

    Retrieves

    Object

    Description

    Return metadata about our data object type in this Jive instance

    ↑
    getOwner(options)
    GET /people/{uri}

    Retrieves

    Person

    Description

    Return the Person representing the user performing this request.

    Options:
    NameTypeRequiredDescription
    fieldsStringfalseNames of the fields to be returned
    Retrieves:
  • Person describing the specified person
    • ↑
    getPrivateProps(options)
    GET /people/{personID}/privateprops

    Retrieves

    PrivateProps

    Description

    ↑
    getRecommendedPeople(options)
    GET /people/recommended

    Retrieves

    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:
    NameTypeRequiredDescription
    countIntegerfalseMaximum number of security groups to return (default is 25)
    fieldsStringfalseNames of the fields to be returned
    Retrieves:
  • Person[] List of recommended people
    • Since: 3.1
    ↑
    getResources()
    GET /people/@resources

    Retrieves

    Resource[]

    Description

    Return metadata about the resources available for our data object type in this Jive instance.

    ↑
    getSupportedFields()
    GET /people/@supportedFields

    Retrieves

    String[]

    Description

    Return the set of fields for our object type that are supported in this Jive instance.

    ↑
    getTermsAndConditions(options)
    GET /people/{personID}/termsAndConditions

    Retrieves

    Object

    Description

    ↑
    getTrendingPeople(options)
    GET /people/trending

    Retrieves

    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:
    NameTypeRequiredDescription
    countIntegerfalseMaximum number of security groups to return (default is 25)
    fieldsStringfalseNames of the fields to be returned
    placeStringfalseURI of a place, users that are trending in this place
    Retrieves:
  • Person[] List of trending people
    • Since: 3.1
    ↑
    getViewer(options)
    GET /people/{uri}

    Retrieves

    Person

    Description

    Return the Person representing the user performing this request.

    Options:
    NameTypeRequiredDescription
    fieldsStringfalseNames of the fields to be returned
    Retrieves:
  • Person describing the specified person
    • ↑
    requestPicker(options)

    Retrieves

    Object

    Description

    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 multiple is false, 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 list field 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:
    NameTypeRequiredDescription
    multipleBooleanfalseFlag indicating whether the user is allowed to select multiple people or not (default is false)
    errorFunctionfalseCallback function that will be called if an error occurs. Passed data object will include a message field containing the error message.
    successFunctionfalseCallback function that will be called if the user successfully selects one or more people. Passed data object will be the corresponding Person object if one person is selected, including all of the instance methods. If multiple people are selected the data object will be an array of Person objects.
    ↑
    savePrivateProps(person,options)
    POST /people/{personID}/privateprops

    Retrieves

    PrivateProps

    Description

    ↑
    search(options)
    GET /search/people

    Retrieves

    Person[]

    Description

    Search for and return people that match the specified filter criteria.

    Options:
    NameTypeRequiredDescription
    countIntegerfalseMaximum number of results to be returned
    fieldsStringfalseNames of the fields to be returned
    nameonlyStringfalseFlag indicating whether to limit search results to only people that match by name (Defaults to false)
    searchStringfalseOne or more search terms, separated by commas. This filter is required. 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.
    startIndexIntegerfalseZero-relative index of the first result to be returned
    Retrieves:
  • Person[] listing the matching people