What is the best way to implement the activity heartbeat?
If you plan to have many such activities I would recommend creating a separate component to heartbeat through executionContext using a Timer to avoid tying a thread to each heartbeat.
What happens when the activity heartbeat fails?
One of the children of an ActivityCompletionException exception will be thrown from the heartbeat call. It is up to the activity implementation to ignore it or exit. Note that from the service and workflow point of view the activity is going to be considered timed out and probably retried.
What is the relationship between scheduleToStart , startToClose , and the heartbeat internal?
ScheduleToStart is the maximum time an activity can stay in a task queue before being picked up. We recommend not setting this value unless you perform host-specific task routing.
StartToClose is the maximum time a single activity attempt can take. It looks like it should be 3 hours in your case.
Heartbeat timeout is the maximum time between heartbeats. It is expected to be relatively small. Let’s say one minute in your case.
It is not really possible to provide hard guarantee that you don’t end up with two activity attempts running at the same time. You can get pretty close by shutting down an activity on an exception thrown from the heartbeat call and setting an initial retry interval larger than the heartbeat interval.
Is there anything else I should be aware of in this scenario?
Activities can include data into a heartbeat call. When an activity is retried the value of the last heartbeat is accessible through ActivityExecutionContext.getHeartbeatDetails call. It might be useful if an activity can resume execution from some previously recorded point.