<< Back to GForge REST API

Entity: Poll

GET

getPoll

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)

rel= Type Description
chat string Forum messages for the specified thread id (in the refId field) - section parameter is ignored. Use one or more chat= params in the GET to specify multiple threads/chat rooms to poll against.
activity string Activity log entries that pertain to the specified section and ref. Use one or more activity= params in the GET to specify, e.g., multiple projects.
wall string Wall postings or other @mentions of the current user.
query string Check to see if the query result has changed. The key for each query item is in the form trackeritem-queryid-lastmodtime, where queryid and lastmodtime are both integers.
tickler string Check to see if the query count has changed. The key for each query item is in the form trackeritem-queryid-lastcount, where queryid and lastcount are both integers.
bgjob string A background job in process.

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


  {"items":[{"type":"wall","section":"user","refId":"5945","lastValue":"0","items":[]},{"type":"chat","section":"project","refId":"138","lastValue":"0","items":[]}]}

POST

PUT

DELETE