Products & Projects

In the Planbox API an initiative is called a product. A product is the first project level, and a project is the second level. A product contains multiple projectsClick here for an overview of objects and their hierarchy in Planbox.

https://work.planbox.com/api/get_product

Retrieves the product. The logged resource must be on that product.

POST Arguments

  • product_id: The product to retrieve.

Result

Returns this JSON object:

{code:<result_code>, content:<result>}

Where <result_code> will be 'ok' on succes, or 'error' on failure.
Where <result> is the product object on success or an error message string upon failure.

A product object has these properties:

  • id: Unique product id
  • name: Name of the product.
  • image: Image URL to product logo.
  • description: Product description.
  • created_on: Date the product was created.
  • creator_id: Resource who created the product.
  • owner_id: Resource id of the product owner.
  • permission: Logged resource permission. Can be one of: read, write or admin. See Planbox Permissions for more information.
  • email_notifications: Email notifications flags for the logged resource.
  • timezone: Product timezone string.
  • template: 1 if this is a template initiative, 0 is not.
  • iteration_start: Date of next iteration start. See Iteration Details for more information.
  • iteration_length: Length of next and future iterations.
  • iteration_length_unit: Unit of iteration length: days, weeks or months.
  • iterations: Array of iteration objects which exist in this product. See Iterations for more information.
  • resource_ids: Array of resource ids involved on this product.
  • project_ids: Array of project ids in this product. Note: The list is curated based on the logged resource permission.
  • capacity: Sum of available work hours for all working resources on this product.
  • token: API Initiative Token. Only available if the logged resource is admin.

An iteration object has these properties:

  • id: Unique iteration id.
  • num: Iteration sequence number. You can order iterations in time using this number.
  • start: Start date of the iteration.
  • end: End date of the iteration. Note: If timeframe is backlog, this is 0000-00-00.
  • timeframe: Iteration timeframe. Can be one of: before_last, last, current, next, after_next or backlog.

Javascript Example

Uses jQuery's post function to fetch the product object for product id 1234.

$.post('https://work.planbox.com/api/get_product', {product_id:1234}, 'json');

https://work.planbox.com/api/get_products

Retrieves the list of products for the logged resource.

POST Arguments

None

Result

Returns this JSON object:

{code:<result_code>, content:<result>}

Where <result_code> will be 'ok' on succes, or 'error' on failure.
Where <result> is an array of products on success or an error message string upon failure.

Each product object is the same as in API call get_product.

Javascript Example

Uses jQuery's post function to fetch all products the logged resource is on.

$.post('https://work.planbox.com/api/get_products', 'json');

Create an initiative (product)

NOTE: This is an alpha version of the API and can change in the future.

Adds a new initiative in the given organization. Any user with 'owner' or 'admin' permissions on
the organization can create an initiative.

POST https://api.planbox.com/organizations/:organization_id/initiatives

Input
  • name: Required string - Name of the product. Default is 'New'.
  • template: Optional boolean - Set to true to create as a template. Default is false.
  • projects: Optional array - Projects that will be created with this initiative. The required keys
    for the given hashes are: name and alias.
{
    "name": "New initiative",
    "template": false,
    "projects": [
        {
            "name": "My first new project",
            "alias": "MFNP"
        },

        {
            "name": "My second new project",
            "alias": "MSNP"
        }
    ]
}

Response
 Status: 201 Created
{
    "id": 1,
    "name": "New initiative",
    "alias": "",
    "description": null,
    "image_url": "https://www.planbox.com/img/product/na.png",
    "created_at": "2013-08-21T21:05:52Z",
    "updated_at": "2013-08-21T21:05:52Z"
    "_links": [
        "organization": {
            "href": "https://www.planbox.com/organizations/1"
        },

        "self": {
            "href": "https://www.planbox.com/initiatives/1"
        }
    ]
}

https://work.planbox.com/api/get_project

Retrieves the projects in a product. The list of projects returned is curated based on the logged user's permission.

POST Arguments

  • product_id: Parent product id.
  • project_id: Project id.

Result

Returns this JSON object:

{code:<result_code>, content:<result>}

Where <result_code> will be 'ok' on succes, or 'error' on failure.
Where <result> is the project object on success or an error message string upon failure.

A project object has these properties:

  • id: Unique project id.
  • name: Name of the project.
  • alias: Short name of project.
  • description: Project description.
  • association: The logged user's association on this project: worker or observer.
  • product_id: Parent product id.
  • resource_ids: Array of resource ids involved on this project.
  • resource_associations: Map of resource ids and their association on this project.
  • resource_roles: Map of resource ids and their role ids on this project.
  • role_ids: Array of role ids on this project.

Javascript Example

Uses jQuery's post function to fetch the project object with id 5678 in product id 1234.

$.post('https://work.planbox.com/api/get_project',
{product_id: 1234, project_id: 5678}, 'json');

https://work.planbox.com/api/get_projects

Retrieves all projects in the given product.

POST Arguments

  • product_id[]: Product or products from which to retrieve stories. You can pass a single product id or an array or product ids.

Result

Returns this JSON object:

{code:<result_code>, content:<result>}

Where <result_code> will be 'ok' on succes, or 'error' on failure.
Where <result> is an array of projects on success or an error message string upon failure.

Each project object is the same as in API call get_project.

Javascript Example

Uses jQuery's post function to fetch all projects for product id 1234.

$.post('https://work.planbox.com/api/get_projects', {product_id:1234}, 'json');

https://work.planbox.com/api/add_project

Adds a new project in the given product. Specify from_project_id to copy resources and their roles from another project. Otherwise, the logged resource will be the new project's first member.

POST Arguments

  • product_id: Product.
  • name: Optional. Name of project.
  • alias: Optional. Alias of project. Up to 10 characters.
  • from_project_id: Optional. if specified, the resources and roles will be copied from that project.

Result

Returns this JSON object:

{code:<result_code>, content:<result>}

Where <result_code> will be 'ok' on succes, or 'error' on failure.
Where <result> has the two properties described below on success or an error message string upon failure.

On success, <result> has these properties:

  • resource: Array of resources. It will contain the logged resource's updated object.
  • project: Array of projects. It will contain the new project. See get_project.

Javascript Example

Uses jQuery's post function to create a new project on product 1234.

$.post('https://work.planbox.com/api/add_project', {
product_id: 1234,
name: 'My new project',
alias: 'MNP'
}, 'json');

Feedback and Knowledge Base