Service calls with return values for platform entity services

[eifinger]

In the discussion #777 it was decided to add return values for services.
home-assistant/core#94759 implemented this decision for the EntityComponent and the calendar platform.

To enable more services to support return values we should add it to EntityPlatform as well.

Pro:

• Enables to get detailed travel time information , including the route Add update_travel_time service to waze_travel_time core#96141
• Enables services to get travel time information for supplied origin/destination without configuring it first
• Enables services for reverse geo-coding to return the resolved address from a set of coordinates. The address might be used to call another service e.g. weather service to get a weather forecast for the current location by city name.

Con:

• Concerns where raised in Support multiple responses for service calls core#96370

[allenporter]

I am not aware of additional concerns to address. My impression is we already have a stance on the primary concern around matching multiple entities, unless there are more implementation details i'm missing. Prior discussions:

• The original architecture discussion high level proposal Service calls with return values #777 :

For entity services: No return values when matching multiple entities

• In the initial PR we omitted from the original PR to reduce its scope while we overhauled and simplified the service call APIs and decided on the implementation detail
• In a followup PR the entity_component was updated when adding calendar which is an entity service enforces the original proposal that no return values are returned when matching multiple entities. The implementation detail is that we decided to raise when multiple entities are matched

To move this forward, I think we need the core architecture folks to weigh in on whether there is something else explicit we're missing here: Either additional concerns around platform entities missed from the original proposal, an implicit desire to support return values for multiple entities (where calendar needs an answer) or if we're on the same page with the prior work here.

[gjohansson-ST]

I assume this applies for home-assistant/core#97280 as well then?

[Shulyaka]

I'd also like to have this feature enabled.
Just because a service call might target multiple entities, it doesn't mean it will.
My use case: I want to create a service for a device, and I need any entity to identify that device. It feels more natural to use platform entity services for that because any entity would do.

So I suggest to start with allowing responses in platform entities when only one entity is targeted. It would be a caller's responsibility to ensure that. Then we can think of extending that into multiple entities.

[allenporter]

Just to clarify -- We've already decided how targets for multiple entities are handled when adding support in needed for calendar (pr).

What are the differences in concerns for platform entities vs the way it is already supported in entity_component to support calendar? As I mentioned in the other thread, I don't understand what else needs to be discussed here.

[gjohansson-ST]

I think (hope so) this discussion is to allow integrations to implement service calls with return values as well as entity components is already allowed to. Coming from Frenck's comment in home-assistant/core#96370
Don't think multiple entities itself is any discussion that needs to be here.

It already works so it only needs to be allowed to do so.

[Shulyaka]

Yes. I apparently made a similar PR: home-assistant/core#97719

[allenporter]

I think (hope so) this discussion is to allow integrations to implement service calls with return values as well as entity components is already allowed to. Coming from Frenck's comment in home-assistant/core#96370 Don't think multiple entities itself is any discussion that needs to be here.

Yes, my question is more specific: what additional discussion needs to happen? What's missing from the original architecture discussion? What are the questions we need to answer or additional considerations we need to talk through for this case? IMO this has all been settled, so I can't tell if there is disagreement or misunderstanding.

[frenck]

Removed the answer, as I thin not enough votes or activity took place.

Based on current knowledge and discussion I have seen in Discord, I really think we should consider different solutions.

With the experience now, and based on previous discussions I had with people (for example @ludeeus), I think we should explore a concept of returning values for the multiple targets.

This, imho, is not a different or separate discussion at all, as entity target are designed to be multiple from the start. Therefore we should at least consider handling them as such for responses as well.

I think we need to fully cover the multiple targets case, before we continue accepting anything at this point.

I will add this topic to a meeting with Paulus, Erik and Martin for upcoming week.

[allenporter]

With the experience now, and based on previous discussions I had with people (for example @ludeeus), I think we should explore a concept of returning values for the multiple targets.
...
I will add this topic to a meeting with Paulus, Erik and Martin for upcoming week.

Thank you for prioritizing the discussion. Just to be clear, i'm happy to keep the discussion moving and do the work to drive it forward. I put out some initial exploration/considerations above in the second half of the answer, and I was sincere about being happy to talk them through. If its more efficient to discuss in the meeting than this discussion thread thats fine with me.

[raman325]

@frenck were you able to make any progress on this? Just curious where we are at, it would be neat to have and I have a use case (zwave_js locks and a service to return user codes)

[frenck]

Yes! I have two paths to write out, however, didn't make it before I left on holiday and are now traveling too

[raman325]

enjoy and look forward to hearing more about it when you return!

[frenck]

Alright, so first of all, sorry for my late reply on this one. I've discussed this with Paulus, Erik, Martin & Robert a bit ago and this is a summary of where this can go.

There are three possible paths:

1. Allow service calls with responses only on a single entity

This means that after resolving the target (including area and/or device), if only a single target entity is left, we are able to return a response. In case a call returns multiple entities, we will raise.

Pro: The nice thing about this is that the response value is just as any non-entity service and thus maybe more familiar.

Cons: When targeting, for example, an area, or when using a template for the target; a change in the environment (e.g., new device added to an area), may cause anything that uses the service to fail all of a sudden. Thus may break automation and script in surprising ways.

2. Return a dictionary when multiple entities are target

When multiple entities are resolved, return a dictionary keyed with the entity ID. For example (in YAML data format for readability in the example):

light.living_room:
 some_value: true
light.kitchen:
 some_value: false

However, when a single entity is targeted, return the normal version:

some_value: true

Pro: The output is kinda more expected. When targeting a single entity you'll just get data from a single entity, when targeting multiple, you'll get multiple.

Cons: When targeting, for example, an area, or when using a template for the target; a change in the environment (e.g., new device added to an area) that cases the response to go from single to multiple results, may cause anything that uses the service to fail all of a sudden as the returned data format changes. This may break automation and script in surprising ways.

3. Always return a dictionary when using entity services

Similar to option 2, expect we will always return a dictionary:

light.living_room:
 some_value: true

and

light.living_room:
 some_value: true
light.kitchen:
 some_value: false

Pro: Consistency

Cons: A little harder to work with / process in templates.

Suggestion

From these perspectives, we lean towards the solution in option 3.

The consistency (and thus avoiding breaking things all of a sudden later on), seems like an important value in this case. As it prevents surprises later on.

While it is a little less friendly to use, it will be consistent in the output provided, while also maintaining the target ability feature that entity service have.

../Frenck

[gjohansson-ST]

My vote is also on option 3 and would be very happy to see this getting implemented shortly.

[allenporter]

Appreciate you taking the time to follow up. This matches my take above in the previous answer (If we want to support multiple entities in a single service call) which is: if we want this a dictionary by entity is needed, and the down side is that templates are more complex.

We'll need a migration plan for the existing entity services which I believe are just calendar and weather. My impression is these are entity services.

Aside: I hesitate to slow this down since i'd rather see the momentum continue :) though I still would like to see some motivating use cases spelled out. e.g. users want to merge weather forecasts. This will help as we consider usability improvements in the future.

[frenck]

We'll need a migration plan for the existing entity services which I believe are just calendar and weather. My impression is these are entity services.

They are. I don't see a good migration path for them myself right now. It would be breaking at this point I guess.

[frenck]

Discussed this today again, this time include the context on the breaking change for the services. And this is what we ended up with:

We are going with option 3 set out above.

This means two services will be breaking: weather.get_forecast and calendar.list_events.
There is no way to ease this and the only solution we see is:

• Introduce new services with a slightly different name, providing the new output from option 3.
• Keep the output of those as is, and deprecate them for 6 month. Raise an repair issue if they are used.

../Frenck

[eifinger]

Edit: Moved follow up question to new discussion: #991