* [polling](polling) - Recommended implementation of an activity that needs to periodically poll an external resource waiting its successful completion.

These samples show three different best practices for polling.

1. [Frequently Polling Activity](./frequent/README.md)

2. [Infrequently Polling Activity](./infrequent/README.md)

3. [Periodic Polling of a Sequence of Activities](./periodic_sequence/README.md)

The samples are based on [this](https://community.temporal.io/t/what-is-the-best-practice-for-a-polling-activity/328/2) community forum thread.

This sample shows how we can implement frequent polling (1 second or faster) inside our Activity. The implementation is a loop that polls our service and then sleeps for the poll interval (1 second in the sample).

To ensure that polling Activity is restarted in a timely manner, we make sure that it heartbeats on every iteration. Note that heartbeating only works if we set the `heartbeat_timeout` to a shorter value than the Activity `start_to_close_timeout` timeout.

To run, first see [README.md](../../README.md) for prerequisites.

Then, run the following from this directory to run the sample:

poetry run python run_worker.py

poetry run python run_frequent.py

The Workflow will continue to poll the service and heartbeat on every iteration until it succeeds.

Note that with frequent polling, the Activity may execute for a long time, and it may be beneficial to set a Timeout on the Activity to avoid long-running Activities that are not heartbeating.

If the polling interval needs to be changed during runtime, the Activity needs to be canceled and a new instance with the updated arguments needs to be started.

import asyncio

from dataclasses import dataclass

from temporalio import activity

from polling.test_service import TestService

class ComposeGreetingInput:

greeting: str

name: str

async def compose_greeting(input: ComposeGreetingInput) -> str:

test_service = TestService()

while True:

try:

result = test_service.get_service_result(input)

return result

except Exception:

activity.heartbeat("Invoking activity")

import asyncio

from temporalio.client import Client

from workflows import GreetingWorkflow

async def main():

client = await Client.connect("localhost:7233")

result = await client.execute_workflow(

GreetingWorkflow.run,

"World",

id="frequent-activity-retry",

task_queue="frequent-activity-retry-task-queue",

)

print(f"Result: {result}")

if __name__ == "__main__":

asyncio.run(main())

import asyncio

from activities import compose_greeting

from temporalio.client import Client

from temporalio.worker import Worker

from workflows import GreetingWorkflow

async def main():

client = await Client.connect("localhost:7233")

worker = Worker(

client,

task_queue="frequent-activity-retry-task-queue",

workflows=[GreetingWorkflow],

activities=[compose_greeting],

)

await worker.run()

if __name__ == "__main__":

asyncio.run(main())

from datetime import timedelta

from temporalio import workflow

with workflow.unsafe.imports_passed_through():

from activities import ComposeGreetingInput, compose_greeting

class GreetingWorkflow:

@workflow.run

async def run(self, name: str) -> str:

return await workflow.execute_activity(

compose_greeting,

ComposeGreetingInput("Hello", name),

start_to_close_timeout=timedelta(seconds=60),

heartbeat_timeout=timedelta(seconds=2),

)

This sample shows how to use Activity retries for infrequent polling of a third-party service (for example via REST). This method can be used for infrequent polls of one minute or slower.

Activity retries are utilized for this option, setting the following Retry options:

- `backoff_coefficient`: to 1

- `initial_interval`: to the polling interval (in this sample set to 60 seconds)

This will enable the Activity to be retried exactly on the set interval.

To run, first see [README.md](../../README.md) for prerequisites.

Then, run the following from this directory to run the sample:

poetry run python run_worker.py

poetry run python run_infrequent.py

Since the test service simulates being _down_ for four polling attempts and then returns _OK_ on the fifth poll attempt, the Workflow will perform four Activity retries with a 60-second poll interval, and then return the service result on the successful fifth attempt.

Note that individual Activity retries are not recorded in Workflow History, so this approach can poll for a very long time without affecting the history size.

import asyncio

from dataclasses import dataclass

from temporalio import activity

from polling.test_service import TestService

class ComposeGreetingInput:

greeting: str

name: str

async def compose_greeting(input: ComposeGreetingInput) -> str:

test_service = TestService()

while True:

try:

result = test_service.get_service_result(input)

return result

except Exception:

activity.heartbeat("Invoking activity")

import asyncio

from temporalio.client import Client

from workflows import GreetingWorkflow

async def main():

client = await Client.connect("localhost:7233")

result = await client.execute_workflow(

GreetingWorkflow.run,

"World",

id="infrequent-activity-retry",

task_queue="infrequent-activity-retry-task-queue",

)

print(f"Result: {result}")

if __name__ == "__main__":

asyncio.run(main())

import asyncio

from activities import compose_greeting

from temporalio.client import Client

from temporalio.worker import Worker

from workflows import GreetingWorkflow

async def main():

client = await Client.connect("localhost:7233")

worker = Worker(

client,

task_queue="infrequent-activity-retry-task-queue",

workflows=[GreetingWorkflow],

activities=[compose_greeting],

)

await worker.run()

if __name__ == "__main__":

asyncio.run(main())

from datetime import timedelta

from temporalio import workflow

from temporalio.common import RetryPolicy

with workflow.unsafe.imports_passed_through():

from activities import ComposeGreetingInput, compose_greeting

class GreetingWorkflow:

@workflow.run

async def run(self, name: str) -> str:

return await workflow.execute_activity(

compose_greeting,

ComposeGreetingInput("Hello", name),

start_to_close_timeout=timedelta(seconds=2),

retry_policy=RetryPolicy(

backoff_coefficient=1.0,

initial_interval=timedelta(seconds=60),

),

)

This sample demonstrates how to use a Child Workflow for periodic Activity polling.

This is a rare scenario where polling requires execution of a Sequence of Activities, or Activity arguments need to change between polling retries. For this case we use a Child Workflow to call polling activities a set number of times in a loop and then periodically call Continue-As-New.

To run, first see [README.md](../../README.md) for prerequisites.

Then, run the following from this directory to run the sample:

poetry run python run_worker.py

poetry run python run_periodic.py

This will start a Workflow and Child Workflow to periodically poll an Activity.

The Parent Workflow is not aware about the Child Workflow calling Continue-As-New, and it gets notified when it completes (or fails).

from dataclasses import dataclass

from temporalio import activity

class ComposeGreetingInput:

greeting: str

name: str

async def compose_greeting(input: ComposeGreetingInput) -> str:

raise RuntimeError("Service is down")

import asyncio

from temporalio.client import Client

from workflows import GreetingWorkflow

async def main():

client = await Client.connect("localhost:7233")

result = await client.execute_workflow(

GreetingWorkflow.run,

"World",

id="periodic-child-workflow-retry",

task_queue="periodic-retry-task-queue",

)

print(f"Result: {result}")

if __name__ == "__main__":

asyncio.run(main())

import asyncio

from activities import compose_greeting

from temporalio.client import Client

from temporalio.worker import Worker

from workflows import ChildWorkflow, GreetingWorkflow

async def main():

client = await Client.connect("localhost:7233")

worker = Worker(

client,

task_queue="periodic-retry-task-queue",

workflows=[GreetingWorkflow, ChildWorkflow],

activities=[compose_greeting],

)

await worker.run()

if __name__ == "__main__":

asyncio.run(main())

import asyncio

from datetime import timedelta

from temporalio import workflow

from temporalio.common import RetryPolicy

from temporalio.exceptions import ActivityError

with workflow.unsafe.imports_passed_through():

from activities import ComposeGreetingInput, compose_greeting

class GreetingWorkflow:

@workflow.run

async def run(self, name: str) -> str:

return await workflow.execute_child_workflow(

ChildWorkflow.run,

name,

)

class ChildWorkflow:

@workflow.run

async def run(self, name: str) -> str:

for i in range(10):

try:

return await workflow.execute_activity(

compose_greeting,

ComposeGreetingInput("Hello", name),

start_to_close_timeout=timedelta(seconds=4),

retry_policy=RetryPolicy(

maximum_attempts=1,

),

)

except ActivityError:

workflow.logger.error("Activity failed, retrying in 1 seconds")

await asyncio.sleep(1)

workflow.continue_as_new(name)

raise Exception("Polling failed after all attempts")

class TestService:

def __init__(self):

self.try_attempts = 0

self.error_attempts = 5

def get_service_result(self, input):

print(

f"Attempt {self.try_attempts}"

f" of {self.error_attempts} to invoke service"

)

self.try_attempts += 1

if self.try_attempts % self.error_attempts == 0:

return f"{input.greeting}, {input.name}!"

raise Exception("service is down")