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

Property	Type	Mode †	Description
`contentTypes`	`String[]`	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.
`creator`	`Person`	read-only	↑ Person that created this project.
`description`	`String`	optional	↑ Human readable description of this place.
`displayName`	`String`	required	↑ 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
`dueDate`	`ISO 8601 Date`	required	↑ Date by which this project must be completed.
`followerCount`	`Integer`	read-only	↑ Number of people following this object. Availability: Will be present only for object types that support being followed.
`highlightBody`	`String`	read-only	↑ Highlight snippet of a search match in the body or description. Availability: Will be present in search results only.
`highlightSubject`	`String`	read-only	↑ Highlight snippet of a search match in the subject or name. Availability: Will be present in search results only.
`highlightTags`	`String`	read-only	↑ Highlight snippet of a search match in tags. Availability: Will be present in search results only.
`id`	`String`	read-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.
`likeCount`	`Integer`	read-only	↑ Number of people who have liked this object. Availability: Will be present only for object types that support being liked.
`locale`	`String`	read-only	↑ Locale string of the space.
`name`	`String`	required	↑ Formal name of this place. It must be unique among places of the same type in this Jive instance.
`parent`	`String`	required	↑ URI of the place that contains this place (if any). URI points at a containing `group` or `space`.
`parentContent`	`Summary`	read-only	↑ Summary information about the content object that is the parent of this object. Availability: Will be present in search results only.
`parentPlace`	`Summary`	read-only	↑ Summary information about the place that contains this object. Availability: Will be present in search results only.
`projectStatus`	`String`	read-only	↑ Current status of this project with respect to its schedule. TODO - enumerate values
`published`	`ISO 8601 Date`	read-only	↑ Date and time when this place was originally created.
`resources`	`Object`	read-only	↑ Resource links (and related permissions for the requesting person) relevant to this object.
`startDate`	`ISO 8601 Date`	required	↑ Date that this project was (or will be) started.
`status`	`String`	read-only	↑ Visibility status of this place ("Active", "Archived", "Deleted").
`tags`	`String[]`	optional	↑ Tags associated with this object. Availability: Will be present only for object types that support tags
`type`	`String`	required	↑ The object type of this object ("project").
`updated`	`ISO 8601 Date`	read-only	↑ Date and time this place was most recently updated.
`viewCount`	`Integer`	read-only	↑ Number of times this place has been viewed. Availability: Will be present only for objects that support view counts
`visibleToExternalContributors`	`Boolean`	optional	↑ Flag indicating that this place is potentially visible to external contributors.

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:

Announcement describing the new announcement

Options:

Name	Type	Required	Description
fields	String	false	Names 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:

Name	Type	Required	Description
uri	String	false	The 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:

Category describing the new category

Options:

Name	Type	Required	Description
autoCategorize	String	false	Flag indicating whether existing content in this place will be categorized in this category based on matched tags
fields	String	false	Names 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:

Name	Type	Required	Description
fields	String	false	Names 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:

Task

Options:

Name	Type	Required	Description
fields	String	false	Names 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:

Name	Type	Required	Description
fields	String	false	Names 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:

Name	Type	Required	Description
after	String	false	Date and time representing the minimum timestamp for returned activities. Cannot specify both after and before
before	String	false	Date and time representing the maximum timestamp for returned activities. Cannot specify both after and before
count	Integer	false	Maximum number of activities to be returned
fields	String	false	Names 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:

Name	Type	Required	Description
count	Integer	false	Maximum number of announcements to be returned
fields	String	false	Names of the fields to be returned
startIndex	Integer	false	Zero-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:

Name	Type	Required	Description
fields	String	false	Names 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:

Name	Type	Required	Description
fields	String	false	Names 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:

Name	Type	Required	Description
count	Integer	false	Maximum number of checkpoints to be returned
fields	String	false	Names of the fields to be returned
startIndex	Integer	false	Zero-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:

Name	Type	Required	Description
fields	String	false	Names 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:

Name	Type	Required	Description
count	Integer	false	Number of followers to be returned (default is 25)
fields	String	false	Names of the fields to be returned
startIndex	Integer	false	Zero-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:

Name	Type	Required	Description
fields	String	false	Names 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:

Name	Type	Required	Description
fields	String	false	Names 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:

Name	Type	Required	Description
fields	String	false	Names 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:

Name	Type	Required	Description
count	Integer	false	Maximum number of tasks to be returned
fields	String	false	Names of the fields to be returned
startIndex	Integer	false	Zero-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:

Name	Type	Required	Description
fields	String	false	Names 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:

Name	Type	Required	Description
fields	String	false	Names of the fields to be returned

Retrieves:

Place describing this place

Resources

Resource	Method	Returns	Description
`avatar`	`GET`	`Object`	↑ Return the binary content of the avatar image for this place.
`html`	`GET`	`Object`	↑ URI of the HTML representation of this place.