Place

Place Service

Web service endpoints for functionality that is common to all places. The standard place types (and corresponding entities) are:

  • blog (Blog) - a blog, associated with this place, in which people can create posts related to activity that is coordinated in this place.
  • group (Group) - a social group, with defined members, typically focused on a particular topic.
  • project (Project) - a project (with associated tasks) to track progress towards particular goals.
  • space (Space) - a formally defined (typically around departmental or topical hierarchies) location for communication about a particular topic.

See Place Use Cases for usage examples.

Create Place

POST /places

Create a new place with specified characteristics, and return an entity representing the newly created place.

The following rules define which fields in the incoming JSON entity are processed:

  • For all place types, the following fields are processed: contentTypes, description, displayName, name, parent, tags.
  • For all place types, the displayName and name fields are required, and must be unique within the parent place.
  • If the parent field is not included, the root space will be the default parent of the new place.
Query Parameters:
NameTypeRequiredDescription
fieldsStringfalseFields to include in the returned entity
Takes:
  • Place describing the place to be created
  • Retrieves:
  • Place representing the newly created place
  • Return Status:
    HTTP Status CodeDescription
    201 (Created)Request was successful
    400 (Bad Request)An input field is malformed
    409 (Conflict)The new entity would conflict with system restrictions (such as two places of the same type with the same name)
    403 (Forbidden)You are not allowed to access the specified place

    Create Place Announcement

    POST /places/{placeID}/announcements

    Create a new announcement associated with this place. An appropriate parent field will be calculated and injected automatically.

    Path Parameters:
    NameTypeRequiredDescription
    placeIDStringtrueID of the place for which to create an announcement
    Query Parameters:
    NameTypeRequiredDescription
    fieldsStringfalseFields to include in the returned Announcement
    Takes:
  • Announcement describing the announcement to be created
  • Retrieves:
  • Announcement representing the newly created announcement
  • Return Status:
    HTTP Status CodeDescription
    201 (Created)Request was successful
    400 (Bad Request)An input field is missing or malformed
    403 (Forbidden)You are not allowed to create announcements in the specified place
    404 (Not Found)The specified parent place cannot be found

    Create Place Avatar

    POST /places/{placeID}/avatar

    Register a new avatar image (or replace an existing one) from the specified URI. The image will be downloaded and scaled as necessary. Note that avatar images are not supported on blogs.

    Path Parameters:
    NameTypeRequiredDescription
    placeIDStringtrueID of the place for which to create or replace an avatar image
    Query Parameters:
    NameTypeRequiredDescription
    uriStringfalseURI of a JPG, PNG, or GIF formatted image
    Retrieves:
  • An HTTP 201 (Created) status if the image was created, or 204 (No Content) if an existing image was replaced
  • Return Status:
    HTTP Status CodeDescription
    201 (Created)Request was successful, and a new image was uploaded
    204 (No Content)Request was successful, and an existing image was replaced
    400 (Bad Request)The specified URI is malformed
    409 (Conflict)This place type does not support avatar images
    404 (Not Found)The specified place or image does not exist

    Create Place Category

    POST /places/{placeID}/categories

    Create a new category for a place with specified characteristics, and return an entity representing the newly created category.

    Path Parameters:
    NameTypeRequiredDescription
    placeIDStringtrueID of the place for which to create a category
    Query Parameters:
    NameTypeRequiredDescription
    autoCategorizeStringfalseFlag indicating whether existing content of the place will be categorized under the new category
    fieldsStringfalseFields to be returned (default is @all)
    Takes:
  • Category describing the category to be created
  • Retrieves:
  • Category representing the newly created category
  • Return Status:
    HTTP Status CodeDescription
    201 (Created)Request was successful
    400 (Bad Request)An input field is malformed or max number of categories has been reached
    409 (Conflict)The new entity would conflict with system restrictions (such as two categories with the same name)
    403 (Forbidden)You are not allowed to manage categories for the place

    Create Place Static with Data

    POST /places/{placeID}/statics

    Create and return a new static resource associated with the specified place. The minimum information needed is:

         {
             "filename" : "{the filename of this resource}"
         }
     
    Takes:
    • Static with at least a "filename" field
    Query Parameters:
    NameTypeRequiredDescription
    fieldsStringfalseNames of the fields to be returned
    Takes:
  • Static describing the static resource to be created
  • Retrieves:
  • Static describing the new static resource
  • Return Status:
    HTTP Status CodeDescription
    400 (Bad Request)Input field is missing or malformed
    409 (Conflict)Attempt to add a second resource with the same filename
    201 (Created)Request was successful
    403 (Forbidden)You are not allowed to manage static resources for this place
    404 (Not Found)Specified place was not found

    Upload New Place Static Data

    POST /places/{placeID}/statics

    Create and return a new static resource associated with the specified place, including the specified data content. The minimum information needed in the JSON object is:

         {
             "filename" : "{the filename of this resource}"
         }
     
    Query Parameters:
    NameTypeRequiredDescription
    fieldsStringfalseNames of the fields to be returned
    Takes:
  • A multipart of subtype form-data that will include a section with a JSON object describing the static resource to be created, and another section containing the content of the static resource
  • Retrieves:
  • Static describing the new static resource
  • Return Status:
    HTTP Status CodeDescription
    201 (Created)Request was successful
    400 (Bad Request)Input field is missing or malformed
    409 (Conflict)Attempt to add a second resource with the same filename
    403 (Forbidden)You are not allowed to manage static resources for this place
    404 (Not Found)Specified place was not found

    Create Place Task

    POST /places/{placeID}/tasks

    Create a Task in a project.

    Path Parameters:
    NameTypeRequiredDescription
    placeIDStringtrueID of the project for which to create a task
    Query Parameters:
    NameTypeRequiredDescription
    fieldsStringfalseFields to include in the returned Task
    Takes:
  • Task containing information describing the new project task
  • Return Status:
    HTTP Status CodeDescription
    201 (Created)Request was successful
    400 (Bad Request)Any of the input fields are malformed
    409 (Conflict)The new entity would conflict with system restrictions (such as two contents of the same type with the same name)
    403 (Forbidden)You are not allowed to access the specified content
    Since: 3.1

    Destroy Place

    DELETE /places/{placeID}

    Delete the specified place.

    Path Parameters:
    NameTypeRequiredDescription
    placeIDStringtrueID of the place to be deleted
    Return Status:
    HTTP Status CodeDescription
    204 (No Content)Request was successful
    400 (Bad Request)An input field is malformed
    403 (Forbidden)You are not allowed to access the specified place
    404 (Not Found)The specified place does not exist

    Destroy Place Avatar

    DELETE /places/{placeID}/avatar

    Delete the existing avatar image for the specified place. Note that avatar images are not supported on blogs.

    Path Parameters:
    NameTypeRequiredDescription
    placeIDStringtrueID of the place for which the avatar image is to be deleted
    Return Status:
    HTTP Status CodeDescription
    204 (No Content)Request was successful
    400 (Bad Request)An input field is malformed
    403 (Forbidden)You are not allowed to delete this image
    404 (Not Found)The specified place or image does not exist

    Destroy Place Category

    DELETE /places/{placeID}/categories/{categoryID}

    Delete the existing category for the specified place. Only admins of the place can manage place categories.

    Path Parameters:
    NameTypeRequiredDescription
    placeIDStringtrueID of the place for which the category is to be deleted
    categoryIDStringtrueID of the category to delete
    Return Status:
    HTTP Status CodeDescription
    204 (No Content)Request was successful
    400 (Bad Request)An input field is malformed
    403 (Forbidden)You are not allowed to delete this image
    404 (Not Found)The specified place or image does not exist

    Get Activity

    GET /places/{placeID}/activities

    Return the activity stream for the specified place.

    Path Parameters:
    NameTypeRequiredDescription
    placeIDStringtrueID of the place for which to return activities
    Query Parameters:
    NameTypeRequiredDescription
    afterStringfalseDate and time representing the minimum "last activity in a collection" timestamp for selecting activities (cannot specify both after and before)
    beforeStringfalseDate and time representing the maxium "last activity in a collection" timestamp for selecting activities (cannot specify both after and before)
    countIntegerfalseMaximum number of activities to return in this request (you may get more activities than this in order to get all of the activities in the last collection)
    fieldsStringfalseFields to be included in the returned activities
    Retrieves:
  • Activity[] listing the requested activities
  • Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    400 (Bad Request)The specified place ID is missing or malformed
    403 (Forbidden)The requesting user is not allowed to retrieve activities for the specified place
    404 (Not Found)The activities or the specified user is not found

    Get Place

    GET /places/{placeID}

    Return the specified place with the specified fields.

    Path Parameters:
    NameTypeRequiredDescription
    placeIDStringtrueID of the place to be returned
    Query Parameters:
    NameTypeRequiredDescription
    fieldsStringfalseFields to be returned
    Retrieves:
  • Place
  • Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    400 (Bad Request)An input field is malformed
    403 (Forbidden)You are not allowed to access the specified place
    404 (Not Found)The specified place does not exist

    Get Place Announcements

    GET /places/{placeID}/announcements

    Return a paginated list of announcements related to the specified place.

    Path Parameters:
    NameTypeRequiredDescription
    placeIDStringtrueID of the place for which to return announcements
    Query Parameters:
    NameTypeRequiredDescription
    startIndexIntegerfalseZero-relative index of the first announcement to be returned
    countIntegerfalseMaximum number of announcements to be returned
    fieldsStringfalseFields to be included in returned announcements
    Retrieves:
  • Announcement[]
  • Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    400 (Bad Request)An input field is missing or malformed
    403 (Forbidden)You are not allowed to access the requested announcements

    Get Place Avatar

    GET /places/{placeID}/avatar

    Return the binary content of the avatar image for the specified place. Note that avatar images are not supported on blogs.

    Path Parameters:
    NameTypeRequiredDescription
    placeIDStringtrueID of the place for which to retrieve the avatar image
    Query Parameters:
    NameTypeRequiredDescription
    sizeStringfalseRequested size ("small", "medium", "large"),default is "large"
    Retrieves:
  • The binary content of the avatar image for the specified place
  • Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    400 (Bad Request)An input field is malformed
    403 (Forbidden)You are not allowed to delete this image
    404 (Not Found)The specified place or image does not exist

    Get Place Categories

    GET /places/{placeID}/categories

    Return categories associated to the specified place.

    Path Parameters:
    NameTypeRequiredDescription
    placeIDStringtrueID of the place to return its categories
    Query Parameters:
    NameTypeRequiredDescription
    fieldsStringfalseFields to be returned (default is @all)
    Retrieves:
  • Category[]
  • Get Place Category

    GET /places/{placeID}/categories/{categoryID}

    Return the specified category of a place.

    Path Parameters:
    NameTypeRequiredDescription
    placeIDStringtrueID of the place that is associated to the category
    categoryIDStringtrueID of the category to return
    Query Parameters:
    NameTypeRequiredDescription
    fieldsStringfalseFields to be returned (default is @all)
    Retrieves:
  • Category containing the specified category
  • Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    404 (Not Found)If the specified category does not exist

    Get Place Followers

    GET /places/{placeID}/followers

    Return a paginated list of Persons about people who are following the specified place.

    Path Parameters:
    NameTypeRequiredDescription
    placeIDStringtrueID of the place to check for followers
    Query Parameters:
    NameTypeRequiredDescription
    startIndexIntegerfalseZero-relative index of the first instance to be returned
    countIntegerfalseMaximum number of instances to be returned (i.e. the page size)
    fieldsStringfalseFields to be returned (or null for summary fields)
    Retrieves:
  • Person listing people following the specified place
  • Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    400 (Bad Request)The request criteria are malformed
    403 (Forbidden)The requesting user is not authorize to retrieve this user information
    404 (Not Found)The specified user cannot be found
    Since: 3.5

    Get Place Following In

    GET /places/{placeID}/followingIn

    Return the list of custom streams in which the requesting user is following this place.

    Path Parameters:
    NameTypeRequiredDescription
    placeIDStringtrueID of the place to check for following
    Query Parameters:
    NameTypeRequiredDescription
    fieldsStringfalseFields to be included in the returned representation
    Retrieves:
  • Stream[] in which the requesting user is following this place
  • Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    400 (Bad Request)An input field is malformed
    403 (Forbidden)You are not allowed to access this place
    404 (Not Found)The specified place does not exist

    Get Place Permissions

    GET /places/{placeID}/permissions

    Return the list of content types that the user is allowed to created for the specified place.

    Path Parameters:
    NameTypeRequiredDescription
    placeIDStringtrueID of the place to check for content types
    Retrieves:
  • array of content types the user is allowed to create on the place.
  • Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    400 (Bad Request)An input field is malformed
    404 (Not Found)The specified place does not exist
    Since: 3.5

    Get Place Places

    GET /places/{placeID}/places

    Return a paginated list of places contained within the specified place.

    This service supports the following filters. Parameters, when used, should be wrapped in parentheses, and multiple values separated by commas. See the examples for clarification.

    Filter Params Example
    search 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*". ?filter=search(test,report)
    tag one or more tags, separated by commas (matching any tag will select a place) ?filter=tag(sales,performance)
    type one or more object types of desired contained places (blog, project, space) separated by commas ?filter=type(blog,project)

    This service supports the following sort types.

    Sort Description
    dateCreatedAsc Sort by the date this place was created, in ascending order
    dateCreatedDesc Sort by the date this place was created, in descending order
    latestActivityAsc Sort by the date this place had the most recent activity, in ascending order
    latestActivityDesc Sort by the date this place had the most recent activity, in descending order
    titleAsc Sort by place name, in ascending order
    Path Parameters:
    NameTypeRequiredDescription
    placeIDStringtrueID of the parent place for which to retrieve contained places
    Query Parameters:
    NameTypeRequiredDescription
    startIndexIntegerfalseZero-relative index at which to start results
    countIntegerfalseMaximum number of places to be returned
    fieldsStringfalseFields to be included in the returned entities
    filterObject[]falseDefined filters to apply when returning places
    sortStringfalseRequested sort order
    Retrieves:
  • Place[] listing the contained places
  • Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    400 (Bad Request)An input field is malformed
    403 (Forbidden)You are not allowed to access this place
    404 (Not Found)The specified place does not exist

    Get Places

    GET /places

    Return a paginated list of places that match the specified filter criteria.

    This service supports the following filters. Parameters, when used, should be wrapped in parentheses, and multiple values separated by commas. See the examples for clarification.

    Filter Params Example
    entityDescriptor one or more objectType,objectID pairs (this filter is likely only useful to those developing the Jive UI itself) ?filter=entityDescriptor(700,1234,14,2345)
    relationship Choose one of the following options:
    • following - Returns places the authenticated user is following.
    • member - Returns social groups the authenticated user is a member of.
    • owner - Returns social groups the authenticated user is an owner of.
    • recentlyviewed - Returns places that the authenticated user recently viewed.
    This filter cannot be combined with other filters. Available since 3.4.
    ?filter=relationship(member)
    search 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*". ?filter=search(test,report) or ?filter=search(10\,000)
    tag one or more tags, separated by commas (matching any tag will select a place) ?filter=tag(sales,performance)
    type one or more object types of desired contained places (blog, project, space) separated by commas ?filter=type(blog,project)

    This service supports the following sort types.

    Sort Description
    dateCreatedAsc Sort by the date this place was created, in ascending order
    dateCreatedDesc Sort by the date this place was created, in descending order
    latestActivityAsc Sort by the date this place had the most recent activity, in ascending order
    latestActivityDesc Sort by the date this place had the most recent activity, in descending order
    titleAsc Sort by place name, in ascending order

    The returned list may contain a mixture of place entities of various types (Blog, Group, Project, and Space). On any given place entity, use the type field to determine the type of that particular place.

    Query Parameters:
    NameTypeRequiredDescription
    filterObject[]falseFilter criteria used to select places
    sortStringfalseRequested sort order
    startIndexIntegerfalseZero-relative index of the first matching place to be returned
    countIntegerfalseMaximum number of places to be returned
    fieldsStringfalseFields to be returned on each place
    Retrieves:
  • Place[] listing the matching places
  • Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    400 (Bad Request)An input field is malformed
    403 (Forbidden)You are not allowed to access specific places
    Since: 3.0

    Get Place Statics

    GET /places/{placeID}/statics

    Return a list of the static resources associated with the specified place.

    Path Parameters:
    NameTypeRequiredDescription
    placeIDStringtrueID of the place for which to retrieve static resources.
    Query Parameters:
    NameTypeRequiredDescription
    fieldsStringfalseNames of the fields to be returned
    Retrieves:
  • Static[]
  • Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    403 (Forbidden)You are not allowed to access static resources for this place
    404 (Not Found)Specified place was not found

    Get Place Tasks

    GET /places/{placeID}/tasks

    Return a paginated list of tasks created for the specified project.

    This service supports the following sort types.

    Sort Description
    dateCreatedAsc Sort by the date this content object was created, in ascending order
    dateCreatedDesc Sort by the date this content object was created, in descending order. Default if none was specified.
    latestActivityAsc Sort by the date this content object had the most recent activity, in ascending order
    latestActivityDesc Sort by the date this content object had the most recent activity, in descending order
    titleAsc Sort by content object subject, in ascending order
    Path Parameters:
    NameTypeRequiredDescription
    placeIDStringtrueID of the project for which to retrieve its tasks
    Query Parameters:
    NameTypeRequiredDescription
    startIndexIntegerfalseZero-relative index at which to start results
    countIntegerfalseMaximum number of places to be returned
    fieldsStringfalseFields to be included in the returned entities
    sortStringfalseRequested sort order
    Retrieves:
  • Task[] listing the project tasks
  • Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    400 (Bad Request)An input field is malformed
    Since: 3.1

    Get Recommended Places

    GET /places/recommended

    Return a list of recommended places. This feature is only available when Jive has enabled the recommender. Do a GET to /api/core/v3/metadata/properties/feature.recommender.enabled to figure out whether recommendation service is enabled or not.

    The returned list may contain a mixture of place entities of various types (Blog, Group, Project, and Space). On any given place entity, use the type field to determine the type of that particular place.

    Query Parameters:
    NameTypeRequiredDescription
    countIntegerfalseMaximum number of places to be returned
    fieldsStringfalseFields to be returned on each place
    Retrieves:
  • Place[] listing the matching places
  • Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    410 (Gone)Recommendation feature is disabled
    Since: 3.1

    Get Root Space

    GET /places/root

    Return the root space for this Jive instance.

    Query Parameters:
    NameTypeRequiredDescription
    fieldsStringfalseFields to be returned on the root space
    Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful

    Get Trending Places

    GET /places/trending

    Return a list of trending places. This feature is only available when Jive has enabled the recommender. Do a GET to /api/core/v3/metadata/properties/feature.recommender.enabled to figure out whether recommendation service is enabled or not.

    The returned list may contain a mixture of place entities of various types (Blog, Group, Project, and Space). On any given place entity, use the type field to determine the type of that particular place.

    Query Parameters:
    NameTypeRequiredDescription
    countIntegerfalseMaximum number of places to be returned
    fieldsStringfalseFields to be returned on each place
    Retrieves:
  • Place[] listing the matching places
  • Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    410 (Gone)Recommendation feature is disabled
    Since: 3.1

    Create Place Following In

    POST /places/{placeID}/followingIn

    Replace the list of Streams in which the requesting user is following this place object.

    Path Parameters:
    NameTypeRequiredDescription
    placeIDStringtrueID of the place object being followed
    Query Parameters:
    NameTypeRequiredDescription
    fieldsStringfalseFields to be returned on the updated list of streams
    Takes:
  • JSON array of Stream objects or URIs
  • Retrieves:
  • Stream[] updated list of streams
  • Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    400 (Bad Request)if any input field is malformed
    404 (Not Found)if the specified person does not exist
    Since: 3.3

    Update Place

    PUT /places/{placeID}

    Update an existing place with specified characteristics.

    The following rules define which fields in the incoming JSON entity are processed:

    • For all place types, the following fields are processed: contentTypes, description, displayName, name, parent, tags.
    • For the processed fields, a value present in the incoming entity will cause the corresponding property on the place to be set to the new value, completely replacing any previous value for fields that are arrays or object structures.
    • For the processed fields, a value not present in the incoming entity will cause the corresponding property in the place to remain unchanged.
    • If the parent field is present, and it is different from the current parent, this place will be moved to become a child of the newly specified parent.
    Path Parameters:
    NameTypeRequiredDescription
    placeIDStringtrueID of the place to be updated
    Query Parameters:
    NameTypeRequiredDescription
    fieldsStringfalseFields to include in the returned entity
    Takes:
  • Place describing the place to be updated
  • Retrieves:
  • Place representing the updated place
  • Return Status:
    HTTP Status CodeDescription
    400 (Bad Request)An input field is malformed
    409 (Conflict)The new entity would conflict with system restrictions (such as two places of the same type with the same name)
    403 (Forbidden)You are not allowed to access the specified place, or to make the requested change in place state

    Update Place Category

    PUT /places/{placeID}/categories/{categoryID}

    Update an existing category with specified characteristics.

    Path Parameters:
    NameTypeRequiredDescription
    placeIDStringtrueID of the place whose category will be updated
    categoryIDStringtrueID of the category to be updated
    Query Parameters:
    NameTypeRequiredDescription
    autoCategorizeStringfalseFlag indicating whether existing content of the place will be categorized under the new category
    fieldsStringfalseFields to be returned (default is @all)
    Takes:
  • Category describing the category to be updated
  • Retrieves:
  • Category representing the updated category
  • Return Status:
    HTTP Status CodeDescription
    200 (OK)Request was successful
    400 (Bad Request)An input field is malformed
    404 (Not Found)The ID of the category does not reference an existing category
    403 (Forbidden)You are not allowed to manage categories for the place