Page MenuHomePhabricator
Diviner Phabricator Tech Docs DoorkeeperJIRAFeedWorker

final class DoorkeeperJIRAFeedWorker
Phabricator Technical Documentation (Doorkeeper)

Publishes feed stories into JIRA, using the "JIRA Issues" field to identify linked issues.

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() — Publishes stories into JIRA using the JIRA API.
  • public function isEnabled() — This worker is enabled when a JIRA authentication provider is active.

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.
  • private function getProvider() — Get the active JIRA provider.
  • private function findUsersToPossess() — Get a list of users to act as when publishing into JIRA.

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.

DoorkeeperJIRAFeedWorker

Publishes stories into JIRA using the JIRA 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.

DoorkeeperJIRAFeedWorker

This worker is enabled when a JIRA authentication provider is active.

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 getProvider()

Get the active JIRA provider.

Return
PhabricatorJIRAAuthProviderActive JIRA auth provider.

private function findUsersToPossess()

Get a list of users to act as when publishing into JIRA.

Return
list<phid>Candidate user PHIDs to act as when publishing this story.

private function shouldPostComment()

This method is not documented.
Return
wild

private function shouldPostLink()

This method is not documented.
Return
wild

private function postComment($account, $jira_key)

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

private function renderStoryText()

This method is not documented.
Return
wild

private function postLink($account, $jira_key)

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