Manage Homes, Communities, and Skills

Your Alexa for Residential administrator users perform several important tasks to create and manage home communities and homes. You must implement certain administrator tasks for the administrators to manage homes, communities, and skills.

Example: How different roles create and manage home communities and homes

The following example shows how the different types of Alexa for Residential administrator roles described in Managing Roles in Alexa for Residential work together to create and manage home communities and homes.

In this example, there are two hypothetical administrators, Ana Carolina Silva and John Doe, who work for a property management company.

Step 1: Register and assign roles

Ana registers her organization with Alexa for Residential.

  • An Alexa organizational unit is created. Ana receives all access permissions for this organization (action: "*").
  • An Alexa for Residential organizational unit is created. Ana is assigned as A4R.OrgAdmin (or A4R.Admin) and receives Alexa organization (amzn1.alexa.org.did.{id}) and Alexa for Residential organization (amzn1.alexa.unit.did.{id}) identifiers to use when calling Alexa for Residential APIs.
  • Ana can now create home communities and homes under the Alexa for Residential organizational unit.

Step 2: Create a home community

Ana creates home community A: amzn1.alexa.unit.f6299588-7e03-4d0d-b55e-765287bbf5aa

  • The A4R.HomeCommunityAdmin user role is created for home community A.
  • Ana is assigned as A4R.HomeCommunityAdmin to home community A.
  • Ana can create, update, or delete home community A, create homes home community A, and manage home community A's resources.

Step 3: Create a home

Ana creates home 100: amzn1.alexa.unit.sdgweghb-7e03-4d0d-b55e-sdfq34ghdfhh

  • Home 100 is in the VACANT state. At this point, the home administrator has complete access to the home's endpoints.
  • The A4R.HomeAdmin user role is created for home 100.
  • Ana is assigned as A4R.HomeAdmin to home 100.
  • Ana can manage home 100 and its resources.

Step 4: Assign the home community administrator role

As shown in the following example, Ana lists user roles for home community A.

{
   "id" : "amzn1.alexa.role.20ba12d5-3afe-4580-8e91-b3cdhdba0253",
   "name" : "A4R.Admin",
   "targetEntityId" : "amzn1.alexa.unit.f6299588-7e03-4d0d-b55e-765287bbf5aa"
}

Ana assigns John to A4R.Admin role amzn1.alexa.role.20ba12d5-3afe-4580-8e91-b3cdhdba0253.

Step 5: Assign the home administrator role

John creates home 200.

  • The A4R.HomeAdmin user role is created for home 200.
  • John is assigned as A4R.HomeAdmin for home 200.
  • John can manage home 200 and its resources.
  • Ana can't manage home 200's resources.

Implement administrator tasks

Implement the following administrator tasks to enable administrator users to perform common residential management activities.

Assign an endpoint to a home

To associate an endpoint with a home, use the Endpoint API to modify the endpoint's associatedUnits field.

Move a resident into a home

When a resident moves in, the home administrator (A4R.HomeAdmin) role transfers the home from the VACANT state to the OCCUPIED state. You accomplish this transfer by calling the set home occupancy API.

At this point, the home administrator loses access to the home's endpoints. This flow restricts administrator access to the home and the home's resources (such as smart home devices) to protect the residents' privacy and security. When the home administrator transfers a home to the OCCUPIED state, the resident can interact with Alexa devices at home and control their home's endpoints.

Move a resident out of a home

When a resident moves out, the administrator must change the home's state from OCCUPIED to VACANT. You accomplish this state change by calling the set home occupancy API.

Manage skills for a home

Use the Skill Management API to manage skills for a home.

To enable a skill for a home, call the enable a skill API.

To disable a skill for a home, call the disable a skill API.

You successfully implemented the tasks that your administrator users must perform to manage homes, home communities, and skills. Next, see Alexa for Residential Device Purchase and Setup to learn how to set up devices and manage them as endpoints.