Page MenuHomeClusterLabs Projects
Diviner Tech Docs DoorkeeperAsanaFeedWorker

final class DoorkeeperAsanaFeedWorker
Phorge Technical Documentation (Doorkeeper)

Publishes tasks representing work that needs to be done into Asana, and updates the tasks as the corresponding Phabricator objects are updated.

Tasks

Configuring Retries and Failures

  • public function getRequiredLeaseTime() — Return the number of seconds this worker needs hold a lease on the task for while it performs work. For most tasks you can leave this at `null`, which will give you a default lease (currently 2 hours).
  • public function getMaximumRetryCount() — By default, Doorkeeper workers perform a small number of retries with exponential backoff. A consideration in this policy is that many of these workers are laden with side effects.
  • public function getWaitBeforeRetry($task) — See @{method:getMaximumRetryCount} for a description of Doorkeeper retry defaults.

Publishing Stories

  • protected function publishFeedStory() — Publish stories into Asana using the Asana API.
  • public function isEnabled() — This worker is enabled when an Asana workspace ID is configured with `asana.workspace-id`.

Story Context

  • protected function getFeedStory() — Get the @{class:PhabricatorFeedStory} that should be published.
  • protected function getViewer() — Get the viewer for the act of publishing.
  • protected function getPublisher() — Get the @{class:DoorkeeperFeedStoryPublisher} which handles this object.
  • protected function getStoryObject() — Get the primary object the story is about, like a @{class:DifferentialRevision} or @{class:ManiphestTask}.

Internals

  • private function loadPublisher() — Load the @{class:DoorkeeperFeedStoryPublisher} which corresponds to this object. Publishers provide a common API for pushing object updates into foreign systems.

Other Methods

Methods

public function getRequiredLeaseTime()
Inherited

PhabricatorWorker

Return the number of seconds this worker needs hold a lease on the task for while it performs work. For most tasks you can leave this at null, which will give you a default lease (currently 2 hours).

For tasks which may take a very long time to complete, you should return an upper bound on the amount of time the task may require.

Return
int|nullNumber of seconds this task needs to remain leased for, or null for a default lease.

public function getMaximumRetryCount()
Inherited

PhabricatorWorker

Return the maximum number of times this task may be retried before it is considered permanently failed. By default, tasks retry indefinitely. You can throw a PhabricatorWorkerPermanentFailureException to cause an immediate permanent failure.

DoorkeeperFeedWorker

By default, Doorkeeper workers perform a small number of retries with exponential backoff. A consideration in this policy is that many of these workers are laden with side effects.

Return
int|nullNumber of times the task will retry before permanent failure. Return `null` to retry indefinitely.

public function getWaitBeforeRetry($task)
Inherited

PhabricatorWorker

Return the number of seconds a task should wait after a failure before retrying. For most tasks you can leave this at null, which will give you a short default retry period (currently 60 seconds).

DoorkeeperFeedWorker

See getMaximumRetryCount() for a description of Doorkeeper retry defaults.

Parameters
PhabricatorWorkerTask$taskThe task itself. This object is probably useful mostly to examine the failure count if you want to implement staggered retries, or to examine the execution exception if you want to react to different failures in different ways.
Return
int|nullNumber of seconds to wait between retries, or null for a default retry period (currently 60 seconds).

public function setCurrentWorkerTask($task)
Inherited

This method is not documented.
Parameters
PhabricatorWorkerTask$task
Return
wild

public function getCurrentWorkerTask()
Inherited

This method is not documented.
Return
wild

public function getCurrentWorkerTaskID()
Inherited

This method is not documented.
Return
wild

final protected function doWork()
Inherited

DoorkeeperFeedWorker

Doorkeeper workers set up some context, then call publishFeedStory().

Return
wild

final public function __construct($data)
Inherited

This method is not documented.
Parameters
$data
Return
this//Implicit.//

final protected function getTaskData()
Inherited

This method is not documented.
Return
wild

final protected function getTaskDataValue($key, $default)
Inherited

This method is not documented.
Parameters
$key
$default
Return
wild

final public function executeTask()
Inherited

This method is not documented.
Return
wild

final public static function scheduleTask($task_class, $data, $options)
Inherited

This method is not documented.
Parameters
$task_class
$data
$options
Return
wild

public function renderForDisplay($viewer)
Inherited

This method is not documented.
Parameters
PhabricatorUser$viewer
Return
wild

public static function setRunAllTasksInProcess($all)
Inherited

PhabricatorWorker

Set this flag to execute scheduled tasks synchronously, in the same process. This is useful for debugging, and otherwise dramatically worse in every way imaginable.

Parameters
$all
Return
wild

final protected function log($pattern)
Inherited

This method is not documented.
Parameters
$pattern
Return
wild

final protected function queueTask($class, $data, $options)
Inherited

PhabricatorWorker

Queue a task to be executed after this one succeeds.

The followup task will be queued only if this task completes cleanly.

Parameters
string$classTask class to queue.
array$dataData for the followup task.
array$optionsOptions for the followup task.
Return
this

final protected function getQueuedTasks()
Inherited

PhabricatorWorker

Get tasks queued as followups by queueTask().

Return
list<tuple<string, wild, int|null>>Queued task specifications.

final public function flushTaskQueue($defaults)
Inherited

PhabricatorWorker

Schedule any queued tasks, then empty the task queue.

By default, the queue is flushed only if a task succeeds. You can call this method to force the queue to flush before failing (for example, if you are using queues to improve locking behavior).

Parameters
map<string,$defaultswild> Optional default options.
Return
this

final public static function awakenTaskIDs($ids)
Inherited

PhabricatorWorker

Awaken tasks that have yielded.

Reschedules the specified tasks if they are currently queued in a yielded, unleased, unretried state so they'll execute sooner. This can let the queue avoid unnecessary waits.

This method does not provide any assurances about when these tasks will execute, or even guarantee that it will have any effect at all.

Parameters
list<id>$idsList of task IDs to try to awaken.
Return
void

protected function newContentSource()
Inherited

This method is not documented.
Return
wild

protected function loadFeedStory()
Inherited

This method is not documented.
Return
wild

protected function publishFeedStory()

DoorkeeperFeedWorker

Actually publish the feed story. Subclasses will generally make API calls to publish some version of the story into external systems.

DoorkeeperAsanaFeedWorker

Publish stories into Asana using the Asana API.

Return
void

public function isEnabled()

DoorkeeperFeedWorker

Enable or disable the worker. Normally, this checks configuration to see if Phabricator is linked to applicable external systems.

DoorkeeperAsanaFeedWorker

This worker is enabled when an Asana workspace ID is configured with asana.workspace-id.

Return
boolTrue if this worker should try to publish stories.

protected function getFeedStory()
Inherited

DoorkeeperFeedWorker

Get the PhabricatorFeedStory that should be published.

Return
PhabricatorFeedStoryThe story to publish.

protected function getViewer()
Inherited

DoorkeeperFeedWorker

Get the viewer for the act of publishing.

NOTE: Publishing currently uses the omnipotent viewer because it depends on loading external accounts. Possibly we should tailor this. See T3732. Using the actor for most operations might make more sense.
Return
PhabricatorUserViewer.

protected function getPublisher()
Inherited

DoorkeeperFeedWorker

Get the DoorkeeperFeedStoryPublisher which handles this object.

Return
DoorkeeperFeedStoryPublisherObject publisher.

protected function getStoryObject()
Inherited

DoorkeeperFeedWorker

Get the primary object the story is about, like a DifferentialRevision or ManiphestTask.

Return
objectObject which the story is about.

private function loadPublisher()
Inherited

DoorkeeperFeedWorker

Load the DoorkeeperFeedStoryPublisher which corresponds to this object. Publishers provide a common API for pushing object updates into foreign systems.

Return
DoorkeeperFeedStoryPublisherPublisher for the story's object.

private function getWorkspaceID()

This method is not documented.
Return
wild

private function getProvider()

This method is not documented.
Return
wild

private function getAsanaTaskData($object)

This method is not documented.
Parameters
$object
Return
wild

private function getAsanaSubtaskData($object)

This method is not documented.
Parameters
$object
Return
wild

private function getSynchronizationWarning()

This method is not documented.
Return
wild

private function lookupAsanaUserIDs($all_phids)

This method is not documented.
Parameters
$all_phids
Return
wild

private function loadAsanaExternalAccounts($user_phids)

This method is not documented.
Parameters
array$user_phids
Return
wild

private function findAnyValidAsanaAccessToken($user_phids)

This method is not documented.
Parameters
array$user_phids
Return
wild

private function makeAsanaAPICall($token, $action, $method, $params)

This method is not documented.
Parameters
$token
$action
$method
array$params
Return
wild

private function newRefFromResult($type, $result)

This method is not documented.
Parameters
$type
$result
Return
wild

private function addFollowers($oauth_token, $task_id, $followers, $silent)

This method is not documented.
Parameters
$oauth_token
$task_id
array$followers
$silent
Return
wild

private function getAsanaProjectIDs()

This method is not documented.
Return
wild

private function addProjects($oauth_token, $task_id, $project_ids)

This method is not documented.
Parameters
$oauth_token
$task_id
array$project_ids
Return
wild

private function getAsanaAccountID($account)

This method is not documented.
Parameters
PhabricatorExternalAccount$account
Return
wild