<< Back to GForge REST API

Entity: Poll



Poll for data in the specified related entities. Each entity will be polled once per polling loop. If any entity returns data, then the loop will exit and return data from all responding entities. If no data is returned by any polled entity, then the loop will repeat until the polling interval has elapsed.

Parameters (2)

Name Type Description
interval int The number of seconds to keep polling, if no data is returned. Can be an integer between 5 and 300, default is 30.
entityname[] string[] For each related entity, specify filter data as needed. See examples for, well, examples. NOTE: You must use the square-brackets in the parameter name, or multiple values will not work. Thanks, PHP!

Related Entities (6)

Return: \gforge\core\models\api\PollResult[]

Zero or more PollResult records, one for each requested related entity that has new data.

Name Type Description
type string Type of poll entity, e.g., chat, activity, mention, etc.
section string Type of the associated object
refId int Id of object associated with this activity log
lastValue int The highest message ID or other relevant value in the list of items being returned. May be 0 or empty if no messages are returned.
items array Array of message elements from the poll response
deleted array

Example 1

Poll for chat data on the GForge5 project thread, waiting up to 30 seconds:
  GET /api/poll?rel=chat&chat[]=forumthread-5367

  {"items":[{"type":"chat","section":"forumthread","refId":"5367","lastValue":103614,"items":[{"id":103611,"subject":"Chat message","body":"brb","postDate":"2014-09-16 16:58:40 -0500","forumThread":5367,"parentForumMessageId":0,"user":{"id":33887,"unixName":"cvizcaya","password":null,"firstname":"Celina","lastname":"Vizcaya","email":"cvizcaya@gforgegroup.com","timezone":"America\/Buenos_Aires","status":1,"externalId":null,"isGroup":"N","ccode":"AR","language":"en   ","theme":1,"img_url":"\/images\/custom_avatars\/33887.jpg","html_url":"\/gf\/user\/cvizcaya\/","details_url":"\/api\/user\/cvizcaya\/details","isSiteAdmin":false,"api_url":"\/api\/user\/cvizcaya"}}] }

Example 2

Poll for new chat data on the GForge5 project (after a previous request's response message ID), and any recent wall posts for a specific user, waiting up to 100 seconds:
  GET /api/poll?interval=100&rel=wall,chat&chat[]=project-138-90054&wall[]=user-5945-0