osapi.jive.corev3.places.Project

A project is a place for recording progress towards a specific goal. A project must have a parent place--there are no global projects. Projects have associated Tasks with individual assignments and due dates. Projects can also have CheckPoints, which are simply a date and description of a checkpoint. An example JSON representation looks like this:

Example:
Example JSON

JSON with the most important data for a Project. See the table below for a list of all fields.

{
  "type" : "project",
  "name" : "Project of a Secret Group",
  "parent" : "https://example.jiveon.com/api/core/v3/places/1435",
  "displayName" : "project-of-a-secret-group",
  "description" : "This is a secret group",
  "status" : "Active",
  "contentTypes" : [ "blog", "documents", "files", "discussions", "polls", "projects", "tasks" ],
  "projectStatus" : "HIGH",
  "visibleToExternalContributors" : false,
  "viewCount" : 2,
  "followerCount" : 1,
  "creator" : {
    "name" : {
      "formatted" : "Administrator"
    },
    "type" : "person",
    "displayName" : "Administrator",
    "id" : "1"
  },
  "startDate" : "2012-07-02T07:00:00.000+0000",
  "dueDate" : "2012-09-14T06:59:59.999+0000",
  "published" : "2012-07-20T17:28:36.304+0000",
  "updated" : "2012-07-20T17:29:20.852+0000",
  "tags" : [ ]
}

Properties

PropertyTypeMode Description
contentTypesString[]optional

Content types that may be included in this place. Valid values are the plural versions of all defined content types (documents, discussions, and so on), plus projects (if projects are allowed in this place) and blog (if a blog is allowed in this place). Additional content types may be available if this Jive instance has installed plugins defining them. During creation, if no content type is specified then all available content types will be selected.

creatorPersonread-only

Person that created this project.

descriptionStringoptional

Human readable description of this place.

displayNameStringrequired

Display name of this place. It must be unique among places of the same type in this Jive instance. This value is used to compose the URL for the HTML presentation of this place in the Jive user interface, so its syntax must conform to the following rules:

  • TODO
dueDateISO 8601 Daterequired

Date by which this project must be completed.

followerCountIntegerread-only

Number of people following this object.

Availability:

Will be present only for object types that support being followed.

highlightBodyStringread-only

Highlight snippet of a search match in the body or description.

Availability:

Will be present in search results only.

highlightSubjectStringread-only

Highlight snippet of a search match in the subject or name.

Availability:

Will be present in search results only.

highlightTagsStringread-only

Highlight snippet of a search match in tags.

Availability:

Will be present in search results only.

idStringread-only

Identifier (unique within an object type and Jive instance) of this object. This field is internal to Jive and should not be confused with contentID or placeID used in URIs.

likeCountIntegerread-only

Number of people who have liked this object.

Availability:

Will be present only for object types that support being liked.

localeStringread-only

Locale string of the space.

nameStringrequired

Formal name of this place. It must be unique among places of the same type in this Jive instance.

parentStringrequired

URI of the place that contains this place (if any). URI points at a containing group or space.

parentContentSummaryread-only

Summary information about the content object that is the parent of this object.

Availability:

Will be present in search results only.

parentPlaceSummaryread-only

Summary information about the place that contains this object.

Availability:

Will be present in search results only.

projectStatusStringread-only

Current status of this project with respect to its schedule. TODO - enumerate values

publishedISO 8601 Dateread-only

Date and time when this place was originally created.

resourcesObjectread-only

Resource links (and related permissions for the requesting person) relevant to this object.

startDateISO 8601 Daterequired

Date that this project was (or will be) started.

statusStringread-only

Visibility status of this place ("Active", "Archived", "Deleted").

tagsString[]optional

Tags associated with this object.

Availability:

Will be present only for object types that support tags

typeStringrequired

The object type of this object ("project").

updatedISO 8601 Dateread-only

Date and time this place was most recently updated.

viewCountIntegerread-only

Number of times this place has been viewed.

Availability:

Will be present only for objects that support view counts

visibleToExternalContributorsBooleanoptional

Flag indicating that this place is potentially visible to external contributors.

→ Fields used by update and create operations
→ Fields used only by create operations
→ Fields not used by update or create operations

Methods

createAnnouncement(announcement,options)
POST /places/1234/announcements

Retrieves

Announcement

Description

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

Here is an example of a JSON with the minimum set of fields you must include:

 {
  "content":
      {
      "type": "text/html",
      "text": "<body><p>Some interesting text</p></body>"
      },
  "subject": "Free beer for everyone"
 }

Takes:
Options:
NameTypeRequiredDescription
fieldsStringfalseNames of the fields to be returned
Retrieves:
  • Announcement describing the new announcement
  • createAvatar(options)
    POST /places/1234/avatar

    Retrieves

    Object

    Description

    Register a new avatar image (or replace an existing one) for this place. The image will be downloaded and scaled as necessary.

    Options:
    NameTypeRequiredDescription
    uriStringfalseThe URI of a JPG, PNG, or GIF formatted image
    createCategory(category,options)
    POST /places/1234/categories

    Retrieves

    Category

    Description

    Create a new category for this place with the specified characteristics, and return an entity describing it. The minimum information required to create a new category is:

       {
         "name": "Animals"
       }
    
    Takes:
    Options:
    NameTypeRequiredDescription
    autoCategorizeStringfalseFlag indicating whether existing content in this place will be categorized in this category based on matched tags
    fieldsStringfalseNames of the fields to be returned
    Retrieves:
  • Category describing the new category
  • createStatic(static,options)
    POST /places/1234/statics

    Retrieves

    Static

    Description

    Create a new static resource for this place with the specified characteristics, and return an entity describing it.

         {
             "filename" : "{filename of the static resource}"
         }
    

    A description field may optionally be included as well.

    Options:
    NameTypeRequiredDescription
    fieldsStringfalseNames of the fields to be returned
    Retrieves:
  • Static describing the new static resource
  • Since: 3.1
    createTask(task,options)
    POST /places/1234/tasks

    Retrieves

    Task

    Description

    Create a new task in the specified project. The minimum information required is:

     {
      "subject": "Clean the carpet",
      "dueDate" : "2013-07-12T06:59:59.999+0000",
      "type": "task"
     }
    
    Availability:

    Available only when the specified person is allowed to create tasks in this project.

    Takes:
    Options:
    NameTypeRequiredDescription
    fieldsStringfalseNames of the fields to be returned
    Retrieves:
  • Task
  • Since: 3.1
    destroy()
    DELETE /places/1234

    Retrieves

    --

    Description

    Delete this place and any related content.

    destroyAvatar()
    DELETE /places/1234/avatar

    Retrieves

    --

    Description

    Delete the existing avatar image for this place.

    get(options)
    GET /places/1234

    Retrieves

    Project

    Description

    Return an updated version of this place.

    Options:
    NameTypeRequiredDescription
    fieldsStringfalseNames of the fields to be returned
    Retrieves:
  • Place describing this place
  • getActivity(options)
    GET /places/1234/activities

    Retrieves

    Activity[]

    Description

    Return a paginated list of activities that have occurred within this place.

    Options:
    NameTypeRequiredDescription
    afterStringfalseDate and time representing the minimum timestamp for returned activities. Cannot specify both after and before
    beforeStringfalseDate and time representing the maximum timestamp for returned activities. Cannot specify both after and before
    countIntegerfalseMaximum number of activities to be returned
    fieldsStringfalseNames of the fields to be returned
    Retrieves:
  • Activity[]
  • getAnnouncements(options)
    GET /places/1234/announcements

    Retrieves

    Announcement[]

    Description

    Return a paginated list of announcements for this place.

    Options:
    NameTypeRequiredDescription
    countIntegerfalseMaximum number of announcements to be returned
    fieldsStringfalseNames of the fields to be returned
    startIndexIntegerfalseZero-relative index of the first announcement to be returned
    Retrieves:
  • Announcement[]
  • getBlog(options)
    GET /places/1234

    Retrieves

    Project

    Description

    Return the blog associated with this place.

    Options:
    NameTypeRequiredDescription
    fieldsStringfalseNames of the fields to be returned
    Retrieves:
  • Blog
  • getCategories(options)
    GET /places/1234/categories

    Retrieves

    Category[]

    Description

    Return the categories associated with this place.

    Options:
    NameTypeRequiredDescription
    fieldsStringfalseNames of the fields to be returned
    Retrieves:
  • Category[]
  • getCheckpoints(options)
    GET /checkpoints/1234/

    Retrieves

    CheckPoint[]

    Description

    Return a paginated list of checkpoints for this project.

    Options:
    NameTypeRequiredDescription
    countIntegerfalseMaximum number of checkpoints to be returned
    fieldsStringfalseNames of the fields to be returned
    startIndexIntegerfalseZero-relative index of the first checkpoint to be returned
    Retrieves:
  • CheckPoint[]
  • getContents(options)
    GET /contents?filter=place(%2Fplaces%2F1234)

    Retrieves

    Project

    Description

    Return the first page of a paginated list of contents that are contained in this place.

    Options:
    NameTypeRequiredDescription
    fieldsStringfalseNames of the fields to be returned
    getFollowers(options)
    GET /places/1234/followers

    Retrieves

    Person[]

    Description

    Return a paginated list of the people following this place.

    Options:
    NameTypeRequiredDescription
    countIntegerfalseNumber of followers to be returned (default is 25)
    fieldsStringfalseNames of the fields to be returned
    startIndexIntegerfalseZero-relative index of the first follower to be returned
    Retrieves:
  • Person[]
  • Since: 3.5
    getFollowingIn(options)
    GET /places/1234/followingIn

    Retrieves

    Stream[]

    Description

    Return the custom streams (if any) in which the requesting person is following this place.

    Options:
    NameTypeRequiredDescription
    fieldsStringfalseNames of the fields to be returned
    Retrieves:
  • Stream[]
  • getPlaces(options)
    GET /places/1234/places

    Retrieves

    Place[]

    Description

    Return the list of child places in this place.

    Options:
    NameTypeRequiredDescription
    fieldsStringfalseNames of the fields to be returned
    Retrieves:
  • Place[]
  • getStatics(options)
    GET /places/1234/statics

    Retrieves

    Static[]

    Description

    Return the list of static resources associated with this place.

    Options:
    NameTypeRequiredDescription
    fieldsStringfalseNames of the fields to be returned
    Retrieves:
  • Static[]
  • getTasks(options)
    GET /places/1234/tasks

    Retrieves

    Content[]

    Description

    Return the first page of a paginated list of tasks for this project.

    Availability:

    Available only when the specified person is allowed to view project tasks.

    Options:
    NameTypeRequiredDescription
    countIntegerfalseMaximum number of tasks to be returned
    fieldsStringfalseNames of the fields to be returned
    startIndexIntegerfalseZero-relative index of the first task to be returned
    Retrieves:
  • Task[] tasks for this project
  • Since: 3.1
    setCheckpoints(checkpoint,options)
    POST /checkpoints/1234

    Retrieves

    CheckPoint[]

    Description

    Replace the existing checkpoints for the specified project with the new ones, and return the updated array of checkpoints. You will need to pass a list that points to an array of checkpoints. Here we see an example of two checkpoints with their minimum set of fields:

    {
        "list": [
            {
                "name": "Feature Complete",
                "dueDate": "2012-07-31T07: 00: 00.000+0000"
            },
            {
                "name": "Code Freeze",
                "dueDate": "2012-09-31T07: 00: 00.000+0000"
            }
        ]
    }
    
    Takes:
    • CheckPoint[] reflecting the new checkpoints for this project.
    Options:
    NameTypeRequiredDescription
    fieldsStringfalseNames of the fields to be returned
    Retrieves:
  • CheckPoint[] reflecting the current checkpoints for this project
  • toURI()

    Retrieves

    String

    Description

    Retrieves:
  • A URI representing this entity, or undefined if no such URI exists.
  • update(place,options)
    PUT /places/1234

    Retrieves

    Place

    Description

    Update the information about this place and return an updated entity.

    Options:
    NameTypeRequiredDescription
    fieldsStringfalseNames of the fields to be returned
    Retrieves:
  • Place describing this place
  • Resources

    ResourceMethodReturnsDescription
    avatarGETObject

    Return the binary content of the avatar image for this place.

    htmlGETObject

    URI of the HTML representation of this place.