Getting Started

## Sections
• [Introduction](https://developers.yonomi.cloud/getting-started/introduction.md): Yonomi Platform Getting Started Guide The Yonomi Platform Getting Started documentation will help a PACS software developer learn the Yonomi Platform purpose, concepts and implementation. It serves as a complete training guide to onboard PACS that are adding support for Yonomi Platform-enabled devices including the XE360 WiFi and other next generation Allegion-brand devices. The Getting Started documentation, along with supplemental materials including the YP Quick Start Claiming Training App and Postman collection, drive the self-paced training. Upon completion, partners should have the knowledge necessary to complete their own YP implementation project.
  • [Overview](https://developers.yonomi.cloud/getting-started/introduction/overview.md): What is Yonomi Platform? Yonomi Platform is Allegion's new cloud-based device connectivity platform. Yonomi Platform provides software developers with: A standardized API for integration Real-time connectivity to devices (i.e., Wi-Fi) Synchronization for offline modes SDKs for mobile application development including device commissioning Additionally, the platform provides Allegion with a standardized connector framework and toolset for adding support for new Allegion devices The benefits of the platform for partners are: Easily and quickly integrate their software solutions to XE360 Wi-Fi As new Allegion devices are released, they can be supported with little additional effort XE360 Wi-fi lock with FleX Module will be the first device supported. Additional devices will be added in the future.
    • [Features](https://developers.yonomi.cloud/getting-started/introduction/overview/features.md): Title Real-time Wi-Fi device connectivity Commissioning SDKs for Mobile apps (initially performed via partner app, built around the SDK) •Device-to-Cloud BLE Proxy Communication •Device Onboarding Connector framework for additional Allegion devices beyond XE360 Wifi Developer APIs to help partners connect their solutions to their devices Cloud Services Integration •Manage Owner Users •Manage Patrons and Permissions •Manage Installations (groups of devices) •Configure Device Settings (ADA compliance, delays, etc.) •View Device State (battery values, current FW version) •Remote Device Control (lock, unlock, etc) •Modify Access Credentials •Firmware Management (OTA, etc.) •Device Audit & Interaction History
    • [Cloud-driven Device Management](https://developers.yonomi.cloud/getting-started/introduction/overview/cloud-driven-device-management.md): With Yonomi Platform, Allegion has transitioned from a firmware-driven to a cloud-driven relationship between PACS and devices. This fundamentally simplifies integration, vastly improves scalability and assures that latest software updates are always available for release on-demand. This shift to cloud-based device management also allows owners to maintain the relationship with their devices and gives Access Partners more control over site management and deployments.
    • [Getting Started FAQ](https://developers.yonomi.cloud/getting-started/introduction/overview/getting-started-faq.md): Why Choose Yonomi Platform? Yonomi Platform brings the following NEW capabilities to Allegion’s connected devices: 1. Real-time connectivity without requiring a local Gateway / PIM allows you to: Know the current status of your devices get closed loop feedback that your updates have been applied get events from your devices when they happen 2. Simplified integrations via cloud APIs, consistent across all new products Faster NPD, better visibility and control over fielded products Future to include remote security management, PKI credentials setup, etc. 3. Expansion of software integration center Ability to layer additional software integrations that can extend value to software partners beyond basic device control How long should it take us to integrate? An average estimate for completing a Yonomi Platform integration project for the first device is is 12-20 weeks, depending on availability and commitment level of an average development team. We believe this can be achievable with: 1-2 cloud engineers 2 mobile application engineers 1 DevOps Resource 1 QA Engineer 1 Applications/Systems Architect /* We will collect and update metrics on project time-frames and update these estimates. */ What does “real-time” mean for YP? In contrast to integration platforms built for once-a-day check in, Yonomi Platform is designed to support devices that have a continuous connection. That means: You can send changes to devices without “touring” them, or having to wait hours for the device to check for updates You receive closed loop feedback that the device accepted your changes, and when those changes failed to apply Your service receives device telemetry data as the events occur Does Yonomi Platform replace Engage? No. ENGAGE lacks the real-time, cloud-based architecture necessary to manage Wi-Fi-enabled devices at scale. Yonomi Platform is the go-forward platform for real-time Wi-Fi devices.
    • [Yonomi Platform Developer Portal](https://developers.yonomi.cloud/getting-started/introduction/overview/yonomi-platform-developer-portal.md): The Yonomi Platform Developer Portal is a self-service management console for partner developers to use to create and configure the objects and systems necessary to complete platform integration. The developer portal allows developers to define platform settings and provides access to documentation, guides and links to API and SDK assets used in project development. Access to the Yonomi Platform is granted by Allegion Customer Success upon request. Speak with your Partner Manager when you’re ready to start a YP integration project.
    • [Schlage XE360](https://developers.yonomi.cloud/getting-started/introduction/overview/schlage-xe360.md): Title Description Title Description Title Description Title Description Title Description Title E X ceeds E X pectations Next level design inside and out Mobile credential support Tested to be cyber secure E X ceptional Value Attractive price point No-Tour or offline system capability Extensive feature set Multiple function options E X tremely Fle X ible Solutions to complete entire property Accommodates changing technology Allegion and 3rd party software options E X panded Solutions Complements Schlage Control® smart locks Popular lever styles & finishe Interoperable for freedom of choice Title Future lock roadmap to be announced at a later date. Title Description Wide Exit Trim Tubular and Mortise
    • [YP No Tour overview](https://developers.yonomi.cloud/getting-started/introduction/overview/yp-no-tour-overview.md): What is No Tour? The No Tour functionality allows property owners and administrators to assign and change access rights without having to physically visit the lock (which is not connected to WiFi) to make access programming updates. This is done by loading credential data on a physical or mobile credential (NFC or BLE). When the credential is next used at the relevant lock, the No Tour data are transferred to the lock’s database. No Tour functionality is currently available for Allegion locks with an Engage integration (see this diagram for an illustration). No Tour for Yonomi Platform devices Certain devices on Yonomi Platform (YP), such as the XE360 Wireless Lock, offer No Tour functionality for when the device is operating in a setting where it is not connected to WiFi. YP support for No Tour aims to enable software partners to offer the ability to manage and interact with No Tour on Engage and YP devices with minimal differences in end-user (e.g. patron and building admin) experience regardless of the platform on which the lock is hosted. This is particularly important for situations where a building may have both Engage and YP devices requiring No Tour functionality. Necessary integration points To ensure consistency of experience with Engage No Tour, YP No Tour support requires integrations with elements of Engage and YP. The constituent parts are an/a: Engage integration via API* to create and manage the relevant Engage site IDs and keys and other Engage-specific No Tour-related data fields (such as lock ID and group ID); Engage integration via API* for the MT20W enrollment reader to add No Tour data to the physical credentials and/or Schlage Mobile Credential integration for mobile credentials (see Mobile No-Tour ) (Note: YP does not differentiate between different types of mobile credentials); YP integration to enable No Tour for relevant devices and to create and manage No Tour lock configuration; and a mapping, maintained by the software partner independently of Engage and YP, of device-level No Tour information with YP identifiers, so that the correct Engage-based No Tour information is passed to a YP-hosted device. *Use of the Engage Web App to manage No Tour does not surface the data that needs to be mapped between Engage and YP. YP No Tour integration points and data fields Example of No Tour user workflow As illustrated below, the Engage integration is necessary to add No Tour information on the credentials. When a No Tour credential is presented to a lock, the response is tracked and communicated to the software partner applications via YP at the next synchronisation opportunity. Note: Configuring the YP device (Step 2 in the diagram) to expect No Tour information is typically done during the lock’s installation on a door. This step provides it with the required information for it to make access control decisions for No Tour credentials. Example of No Tour user workflow
    • [BLE Proxy overview](https://developers.yonomi.cloud/getting-started/introduction/overview/ble-proxy-overview.md): What is BLE Proxy? When a YP-hosted device is not connected to WiFi or is not WiFi-enabled, communication between the cloud and the device does not happen in real time. Changes to settings, action requests, or notifications generated by the device therefore need to be relayed from the offline device to the cloud by physically visiting it with the mobile app (i.e. “touring” it). On YP, this is done via what is known as BLE Proxy, available in the YP Device Communication SDK. BLE Proxy acts as a bridge between the device and cloud by maintaining a secure BLE session with the device while forwarding messages. All messages being relayed are encrypted. BLE Proxy does not know the content of the payloads it is relaying. Which SDK do I need? The YP Device Communication SDK, available on iOS and Android, provides the BLE Proxy functionality. This is the same SDK that is used for initial setup of a YP-hosted device, including scanning nearby devices, obtaining the claim token, and connecting a device to WiFi. Please see the README file in GitHub for more details. GraphQL and BLE Proxy use cases Note: See the sub-pages to this section for implementations diagrams for firmware update, syncProperties and syncDeviceCommands. BLE Proxy relays messages between the cloud and the device when a device is offline. Depending on the workflow, there are different SDK actions that need to be used (see the README file for additional details): syncProperties, which relays messages from the cloud to the device relating to updating a setting value, such as AutoRelockDelayV1 . Typically, this covers any trait action mutation that includes the word “Set”, e.g. SetAutoRelockDelay . Any DEVICE_STATE_UPDATED or DEVICE_BULK_DATA_STATE_UPDATED event requires syncProperties; syncDeviceCommands, which relays messages from the cloud to the device relating to an action request. Typically, any trait action mutation with "Execute", "Trigger", or "Schedule" would require syncDeviceCommands. Current examples are: LockV1ExecuteLockingAction , FirmwareV1InstallLatestFirmwareUpdate , and FirmwareV1ScheduleLatestFirmwareUpdate ; and syncTelemetry, which relays device-generated messages from the device to the cloud, such as notifications regarding battery levels (see BatteryV1 ). Any DEVICE_NOTIFICATION_REPORTED event requires syncTelemetry.
      • [Firmware update](https://developers.yonomi.cloud/getting-started/introduction/overview/ble-proxy-overview/firmware-update.md): The diagram below shows the recommended implementation of the workflow for updating firmware via BLE Proxy, i.e. when the device is not connected to WiFi. Firmware update workflow over BLE Proxy
      • [syncProperties](https://developers.yonomi.cloud/getting-started/introduction/overview/ble-proxy-overview/sync-properties.md): The diagram below shows the recommend implementation of the workflow for updating syncing properties via BLE Proxy, i.e. when the device is not connected to WiFi. Sync properties over BLE Proxy
      • [syncDeviceCommands](https://developers.yonomi.cloud/getting-started/introduction/overview/ble-proxy-overview/sync-commands.md): The diagram below shows the recommend implementation of the workflow for updating syncing commands via BLE Proxy, i.e. when the device is not connected to WiFi. Syncing commands over BLE Proxy
    • [YP DCSDK How-Tos](https://developers.yonomi.cloud/getting-started/introduction/overview/yp-dcsdk-how-tos.md): This section contains articles on how to use the Yonomi Platform Device Communication SDK for various different workflows. It will be updated as documentation becomes available.
      • [Device Scanning](https://developers.yonomi.cloud/getting-started/introduction/overview/yp-dcsdk-how-tos/device-scanning.md): Your mobile applications may integrate with two or more Allegion SDKs. Examples of needing to do this include: to offer device setup and management of YP and Engage devices in a single app, or to offer device management and mobile credentials in the same app. Today, while certain versions of the Allegion SDKs are compatible with each other (consult their respective Readmes and repositories for more information), the workflow of scanning for devices is separate for each SDK. However, there are ways to order operations that improve user experience, especially in terms of waiting time. Outlined below is an approach that may improve user experience in your mobile app when integrating with more than one Allegion SDK, if you wish to combine the results of scanning operations. It is, of course, possible to keep the scanning workflows separate and provide the user the ability to scan for devices using the appropriate SDK for their selection (e.g. select ‘Engage’ or a specific Engage device to scan for Engage devices, and similarly with YP devices). In this example, the mobile application provides the means to manage YP- and Engage-hosted devices. One possible implementation would be: By tapping a single ‘scan’ option (or similar), the user triggers the scanning of all available compatible devices. This trigger begins scanning operations for both Engage-hosted devices (via the EDC SDK) and YP-hosted devices (via the YPDC SDK) to run in parallel to save time. You can also do this in series, but this will take longer overall. When both scanning operations have completed, your app will need to aggregate the separate lists and present the combined results to the user. This will provide the user with the full list of in-range available devices with which they can work, instead of running sequential and separate workflows for Engage- and YP-hosted devices. Additional performance note: Check the release notes of your Allegion SDKs for details on whether they include the Common Core or “BLE caching”. This includes a feature for BLE peripheral caching that, when enabled on a given SDK, can provide a quicker scanning experience by caching the scan data.
• [Yonomi Platform Concepts](https://developers.yonomi.cloud/getting-started/yonomi-platform-concepts.md): This section covers basic Yonomi Platform concepts that a developer must understand to build a successful integration to Yonomi Platform. Concrete definitions of each concept will be provided as reference. Refer back to this section as necessary to understand the various Yonomi Platform objects and concepts and relationships between them.
  • [General Terms: Roles](https://developers.yonomi.cloud/getting-started/yonomi-platform-concepts/general-terms-roles.md): Title Description PACS Partner – A Physical Access Control Partner of Allegion. Sometimes referred to in this training as just “Partner”. PACS Developer – A software developer working for a PACS to integrate Yonomi Platform with their company’s Access Control solutions. Owner/Client - The company who has purchased Allegion Hardware and has a client/customer relationship with the PACS Partner. Integrator – The company responsible for physical installation of Allegion hardware. Patron – The individual who operates a door secured by Allegion hardware.
  • [General Terms: Concepts](https://developers.yonomi.cloud/getting-started/yonomi-platform-concepts/general-terms-concepts.md): Title YP Developer Portal – Yonomi Platform Admin Management & Configuration Console. Installation - a deployment of Allegion hardware owned by an Owner. Organization - a collection of Installations. Dev Resource Group - a container for all resources used to develop integrations for YP Integration Application Client - an application requesting access to a protected Yonomi Platform resource on behalf of the Resource Owner, such as the Owner. Access Tokens are generated using Clients. Webhook Identity Federation - a method of linking a user’s identity across multiple separate Identity Management Systems (IdMs). Factory Provisioning - the process of preparing a device for claiming, occurring before the device leaves an Allegion factory. Device Claiming - the process of associating a device with a specific owner site installation and PACS-managed relationship.
  • [YP Developer Portal Account](https://developers.yonomi.cloud/getting-started/yonomi-platform-concepts/yp-developer-portal-account.md): A YP Developer Portal Account is a named admin user account created in the Yonomi Platform Developer Portal that allows a partner developer to log in and create, configure and manage their YP environment. Allegion partners will be granted – and will need – only one developer portal account, regardless of the number of developers in their company. The developer account will be used to create all objects necessary to configure and complete YP integration projects. The YP Developer Account should be treated as a root/admin account and handled with the Principle of Least Privilege (PoLP). This account is not and should not be used to generate access tokens for API calls.
  • [Dev Resource Group](https://developers.yonomi.cloud/getting-started/yonomi-platform-concepts/dev-resource-group.md): A Dev Resource Group is a container for all resources used to develop integrations for Yonomi Platform. The Dev Resource Group is created in the YP Developer Portal by a PACS Partner Admin using their YP Portal Developer Account. Partners will create only one Dev Resource Group to manage all objects associated with their client deployments, regardless of the number of clients or sites they manage. Dev Resource Groups are associated with a Developer Portal account. Partners will be granted – and need – only one dev resource group – and so Dev Resources Groups have a 1:1 relationship with Developer Portal Accounts. In the future, multiple developer accounts may have access to their company’s Dev Resource Group.
  • [Installation](https://developers.yonomi.cloud/getting-started/yonomi-platform-concepts/installation.md): An installation is a deployment of Allegion hardware owned by an Owner. Installations are created using the YP GraphQL API. An owner may manage one or multiple physical sites using a single installation: Alternatively, an owner may associate each physical site with its own installation: Which organizational approach is used is up to the PACS and how they’ve structured their integration with Yonomi Platform to manage installations. An installation for YP is different than an installation than a “site” in Engage.
  • [Organization](https://developers.yonomi.cloud/getting-started/yonomi-platform-concepts/organization.md): An organization is a collection of installations (Allegion hardware deployment). Organizations are created using the YP GraphQL API. As a best practice, only one organization should exist per owner/client. Organizations represent the owner entity themselves. As such, it is critically important that installations representing deployments of hardware owned by different owners not be associated with the same organization. Organizations must only be associated with installations from the same owner/client. Not adhering to this design principle can result in hardware maintenance & management issues in the future.
  • [Integration](https://developers.yonomi.cloud/getting-started/yonomi-platform-concepts/integration.md): An Integration is a relationship object in Yonomi Platform that allows PACS Partners to establish & advertise their availability as a supported YP partner to owners and allow owners to choose a partner to manage their devices. Integrations allow partners to operate and manage devices on an owner’s behalf and receive and process device-related events. Integrations are created in the YP Developer Portal under a Dev Resource Group. Dev Resource Group may contain many Integrations. It is best practice to establish unique integrations per staging environment (Dev, QA, Prod). Owners typically establish a sole partner integration relationship for operational needs across all their physical sites. (This approach is not a functional requirement; how you create and manage integrations depends on your access control solution implementation and architecture needs.) Integrations can be designated as either private (not searchable) or public (searchable). Public integrations can be discovered by owners and associated with the owner’s organization.
  • [Application Clients](https://developers.yonomi.cloud/getting-started/yonomi-platform-concepts/application-clients.md): An Application Client is an application requesting access to a protected Yonomi Platform resource on behalf of the Resource Owner, such as the Owner. Access Tokens are generated using Clients. An Access Tokens is a user credential that act as an electronic key to Yonomi Platform APIs, ensuring that an API user has the correct permissions to access the service being requested. In Yonomi Platform, clients allow Partners to generate JWT-based access tokens used for API Requests. PACS Partners create Clients in the YP Developer Portal. They are contained within Dev Resource Groups. Yonomi Platform exposes 2 types of Application Clients for developers to use when building apps: User Scope Clients are used to generate access tokens to build apps that a PACS Partner’s Clients/Owners, Integrators or Patrons will use to manage, monitor and operate devices. PACS Partners will build these apps as part of their integration to Yonomi Platform. User Scope Access Token identity is managed by PACS Partners through federated identity (covered later) and access tokens represent the identity of the user for which the token was created. Machine-to-Machines (M2M) Clients are used to generate access tokens to build apps that PACS themselves or other services will use for administrative use cases such as service-level visibility, device health , tamper monitoring or fleetwide firmware management. M2M Clients are not associated with any one user identity; M2M clients represent requests made on behalf of applications. M2M Clients must be granted authorization to a public Integration for their access tokens to have read-level visibility to associated Organizations & Installations.
    • [User Scope Clients vs. M2M Clients](https://developers.yonomi.cloud/getting-started/yonomi-platform-concepts/application-clients/user-scope-vs-m2m-clients.md): User Scope Clients and M2M Clients are intended for different uses and have different API access scopes that limit their use across use cases. The table below explains different operations available for each client type, along with coverage of what is only done in the YP Dev Portal.
    • [Client Use Cases](https://developers.yonomi.cloud/getting-started/yonomi-platform-concepts/application-clients/client-use-cases.md): User Scope Clients and M2M Clients are intended to be used to build different applications and have different API access scopes that limit their use across use cases. The table below explains different use cases recommended for each client type.
  • [Webhook](https://developers.yonomi.cloud/getting-started/yonomi-platform-concepts/webhook.md): A Webhook is a service configuration in Yonomi Platform used to allow Yonomi Platform to send device and service-related events and data directly to PACS Partners for processing. Webhooks are means by which Yonomi Platform dispatches real-time device state changes and other event notifications to PACS Partners. PACS Partners create and configure webhooks in the YP Developer Portal as a component of a Dev Resource Group by supplying an API endpoint that will be used to capture data sent by Yonomi Platform anytime a device state changes, or any other event emits. Subscriptions are configured by associating a webhook with an Integration and selecting the events to which the PACS Partner wants to subscribe. Event types include: Device State Updated (such as a lock state change from “locked” to “unlocked”) Device Action Created (such as a request to change a lock’s state from “locked“ to “unlocked“) Device Action Updated (such as the status of the action request being fulfilled successfully) Device Notification Reported (such as critical battery level notification) Webhook events occur in real-time – they are sent from YP over the webhook immediately upon the state of a device changing or action being requested. Retries If the webhook endpoint returns a non-2xx response code, Yonomi retries failed webhook deliveries. Webhooks are delivered via AWS SNS HTTPS subscriptions using the default delivery policy: 3 retries after the initial attempt, with a 20-second delay between each attempt (linear backoff). There is a maximum of 4 total delivery attempts. If all attempts fail, the event is not recoverable.
    • [Securing webhooks](https://developers.yonomi.cloud/getting-started/yonomi-platform-concepts/webhook/securing-webhooks-with-basic-auth.md): When adding a new or editing a current webhook, you have the option to add Basic Auth. This provides a layer of security to ensure that messages posted to your webhook URL(s) come from a source that has access to appropriate Basic Auth credentials. This increases confidence that these messages are sent by Yonomi Platform. To add Basic Auth to a webhook in the Yonomi Platform Dev Portal, toggle on “Enable Basic Auth” and complete the required Username and Password fields. The tooltips provide information on necessary input requirements. Once completed, save your changes to add or edit your webhook. Adding Basic Auth to a webhook Technical notes Our Basic Auth service will try first to post a message without auth. To ensure that it retries with Basic Auth, your webhook service will need to respond always with a 401 HTTP response and a WWW-Authenticate response header if an incoming request does not include Basic Auth. The WWW-Authenticate response header will need to contain a realm, e.g. "WWW-Authenticate": ‘Basic realm="(arbitrary value)"’. Webhook requests that use Basic Auth credentials will have an Authorization header with value: Basic [<Username>:<Password> (base64 encoded)] per basic auth convention.
  • [Relationship between Integrations, Organizations and Installations](https://developers.yonomi.cloud/getting-started/yonomi-platform-concepts/relationship-between-integrations-organizations-and-installations.md): Integrations are owned by PACS Partners . Organizations and Installations are owned by Owners . Integrations represent a relationship through which PACS Partners are permitted to manage the installations in owner’s organization. Owners grant PACS Partners permission to manage their hardware installations by granting that authority to a PACS Partner’s Integration object.
  • [Identity Federation](https://developers.yonomi.cloud/getting-started/yonomi-platform-concepts/identity-federation.md): Yonomi Platform uses federated identity to allow PACS Partners to manage B-Y-O Identity for their clients/owners, integrators and other end users of their solutions. Federated Identity is a method of linking a user’s identity across multiple separate Identity Management Systems (IdMs). It allows users to quickly and reliably establish identity across systems while maintaining security. Yonomi relies on the Open ID Connect and OAuth2.0 protocol standards, respectively, to authenticate and authorize users managed by PACS Partner’s IdM(s). These standards are supported standard by all major IdM solution providers today. Federated Identity Management is configured in the Yonomi Platform Developer Portal. Once configured, Yonomi GraphQL API will use values in the audience and scope claims defined in access token JWTs generated by the PACS IdM to verify authorization of each API request. Federated Identity Management is a requirement for Yonomi Platform.
  • [Device Claiming](https://developers.yonomi.cloud/getting-started/yonomi-platform-concepts/device-claiming.md): Claiming a device involves: 1. Powering on & connecting to a device via BLE from a mobile app using the YP SDK 1. 2. Obtaining a claim token from the device using the YP SDK (via a mobile app) 3. Configuring the device with a WiFi Connection so it can call “home” to Yonomi Platform (WiFi connection not required, may be brokered connection from mobile over BLE) 4. Performing a claim request via the YP GraphQL API to associate the device with a PACS-managed installation
• [Architecture](https://developers.yonomi.cloud/getting-started/architecture.md): Yonomi Platform: The Channel to Allegion's Ecosystem of Newest Devices and Services
  • [The Yonomi Platform Solution](https://developers.yonomi.cloud/getting-started/architecture/the-yonomi-platform-solution.md): The Yonomi Platform provides a standardized connector framework and toolset that allows PACS to easily integrate their solutions to new Allegion devices. As new devices are released, they can be supported with little additional effort. Below is a high-level view of the entire Yonomi Platform Solution. A PACS software developer uses YP's services and APIs to build, maintain, and monitor thier integration. A software developer uses their product and servics to deliver value to their customer to allow them to manage and monitor Allegion devices on their property.
  • [Technology Stack overview](https://developers.yonomi.cloud/getting-started/architecture/technology-stack-overview.md): Yonomi Platform is a part of a full stack that delivers value. Yonomi is a platform of software services, APIs, SDKs, Firmware libraries and associated tools that allow a customer's software products/services to manage compatible devices. Yonomi Platform eliminates barriers to adoption for connected products and accelerates new product development of Allegion's connected portfolio.
  • [Core Components](https://developers.yonomi.cloud/getting-started/architecture/core-components.md): The platform uses MQTT and BLE to communicate to devices via SDK directly, in real-time, and indirectly. The platform uses GraphQL/HTTPS to communicate from and to the cloud over APIs.
  • [Platform Interface](https://developers.yonomi.cloud/getting-started/architecture/platform-interface.md): Title Description Title Description Title Description Title Description Title Description Title GraphQL Benefits: Static typing = faster development, fewer coding errors Building a request can happen organically You only request what you need The response data is the same shape as the request – makes building APIs much easier Traits: The Trait language is our proprietary unifying language for connected devices Outcome: Bring Partners To Market Faster
  • [Traits](https://developers.yonomi.cloud/getting-started/architecture/traits.md): What are Traits? A Trait is a JSON data element that represents the data schema that describes specific device functionality within Yonomi Platform. A 'Trait' represents a single composable unit of device capability, functionality, or behavior. Yonomi Platform uses traits to expose device interactions via its GraphQL API. Traits are designed to capture the core functionality of devices in a standardized manner, making integration more accessible and reducing the time required for device integration. Traits ensure that the functionality of devices within YP can be composed together seamlessly while still allowing for flexibility. Using traits, devices can be integrated more effectively, allowing for standardized interactions and a consistent user experience. Traits address 3 different types of device functionality: States Actions Notifications Trait Attributes Overview States State represents the current state of specific functionality or persisted data related to the device. For example, in a lock trait, the state could represent the current lock status. Actions Actions enable interaction with devices from the cloud. Actions can be executed on a device and may take action-arguments. Actions can cause changes in the device's behavior or settings, such as changing the lock status or timezone settings. They can also trigger temporary effects like playing an alert or flashing a light. Notifications Notifications communicate transient information from the device to the platform or users. Examples of notifications include when a lock enters passage or secure mode and what caused the change.
  • [Queries](https://developers.yonomi.cloud/getting-started/architecture/queries.md): What are Queries? Queries are API requests to retrieve the state(s) or value(s) of one or more objects in Yonomi Platform. YP device data can be queried with as many or as few traits and associated data as needed using GraphQL fragments. It’s important to note that queries pull data from the Device Shadow in the cloud – not the device. This means queries DO NOT impact device battery life. To determine the fields for the fragment, please refer to the traits documentation or perform an introspection using the GraphQL Schema.
• [Training Project](https://developers.yonomi.cloud/getting-started/training-project.md): With Yonomi Platform concepts complete, the remainder of this training will focus on a hands-on project exercising all aspects of the topics you’ve reviewed. This training will focus on a multifamily project. Your role and objective: Fictitious Allegion PACS partner Romanworks would like to add XE360s to their portfolio of supported devices on the Romanworks Access Control Platform, their ACS. They would then like to onboard Acme Living LLC as a customer. Acme Living’s first installation site for devices will be 125 Ocean Ave in Miami . We will operate under the following personas for this project: Title Description “ Darryl “ will be referenced as the name of developer at Romanworks who will be doing development “ Anna ” will be the property manager at Acme Living who owns the locks and building at 125 Ocean Ave “ Ivonne ” will be the integrator responsible for installing and setting up hardware ” Paully ” will be the patron of Anna’s building at 125 Ocean Ave
  • [Training Project Solution Goal](https://developers.yonomi.cloud/getting-started/training-project/training-project-solution-goal.md): Project: Configure a complete Yonomi Platform implementation with simulated Access Control System (using postman, webhooks and Auth0)
    • [What We Will Build](https://developers.yonomi.cloud/getting-started/training-project/training-project-solution-goal/what-we-will-build.md): Configuring the YP Developer Portal Establish a Yonomi Dev Portal Account Create a Dev Resource Group Create a Public Integration Create a Machine-to-Machine Application Client Create a Webhook Configuration (using a pre-existing webhook endpoint) Configure an Identity Federation Configuration (using a pre-existing Auth0 Training IdM tenant) Create a User Scope Application Client Using the YP GraphQL API (using Postman) Use YP GraphQL APIs to create Organization and Installation objects on behalf of ACME Living Use the API to connect the ACME Living Organization to the Romanworks Public Integration Using the YP Device Communication SDK (using pre-built Training App) Use a pre-built training app (and YP SDK) to configure a lab XE360 for WiFi Communication Use app to obtain a claim token and claim the lab XE360 YP Events (Webhooks) Monitor Device Events & Notifications (webhooks) Working with Devices (Back to the GraphQL API) Use the GraphQL API to send queries, change device settings and configure the lock Add a credential to a lock Review Historical Events
    • [What's Not Covered](https://developers.yonomi.cloud/getting-started/training-project/training-project-solution-goal/what-s-not-covered.md): In this training you will not: Create a patron app Create an installer app Work with NFC or BLE Mobile Credentials (topic of a separate training)
  • [Training: YP Developer Portal](https://developers.yonomi.cloud/getting-started/training-project/training-yp-developer-portal.md): Romanworks Developer Darryl will start their journey with Yonomi Platform by requesting access to and logging in to the YP Developer Portal. To request access, Darryl will send an email to Allegion Customer Success at developer.support@allegion.com and include the PACS name and project details, including: Project/First Target Customer name and Address (or “none” if there is no initial target) Project Go-Live target timeframe Project Lead name and email List of Developer names/emails who need YP Dev Portal (will also be granted Slack access). Acknowledgement of signed NDA and where applicable API (beta) Use Agreement The Allegion Customer Success team will receive, verify and process this request to grant Developer Portal Access.
    • [Login to YP Developer Portal](https://developers.yonomi.cloud/getting-started/training-project/training-yp-developer-portal/login-to-yp-developer-portal.md): Once access has been granted, Darryl will log into the portal: 1. Access Yonomi Platform Developer Portal 1. Browse to https://services.yonomi.cloud 2. You’ll need to set your own password using the Forgot Password feature: Click the Login button to get to the authentication screen, Click the Forgot password? link Enter your email address and click Continue Check for the email sent from Yonomi that will allow you to change your password and click the link. If the link is expired, follow the 3 steps above again to get a new link. Set your new password After completion, follow the link to log in to the Yonomi Platform Developer Portal. 3. Log in to the portal using your email and password and setup 2-factor authentication Upon first login, you’ll be required to configure 2-factor authentication. Scan the QR code presented on the screen with your preferred 2-factor authentication app, then enter your one-time use code to authenticate your account. Some examples of 2-factor authentication apps include: Microsoft Authenticator (download from app store) Google Authenticator (download from app store) After first login, you’ll be directly challenged with 2-factor authentication for future logins.
    • [Training: Create a Dev Resource Group](https://developers.yonomi.cloud/getting-started/training-project/training-yp-developer-portal/training-create-a-dev-resource-group.md): 4. Once logged in, the first step Darryl will complete is to create a Dev Resource Group. The Dev Resource Group is a container for all resources Darryl will use to develop integrations between the Romanworks Access Control Platform and Yonomi Platform. Click the + Add Dev Resource Group button Provide a name Click Create Dev Group Once complete, your new Dev Resource Group will be listed on the left-hand menu with additional objects that can now be configured as part of the group.
      • [Dev Resource Groups Elements](https://developers.yonomi.cloud/getting-started/training-project/training-yp-developer-portal/training-create-a-dev-resource-group/dev-resource-groups-elements.md): Now that Darryl has a Dev Resource Group, we can walk through the different elements now visible that make up a Dev Resource Group.
        • [YP Dev Portal: Organization ID](https://developers.yonomi.cloud/getting-started/training-project/training-yp-developer-portal/training-create-a-dev-resource-group/dev-resource-groups-elements/organization-id.md): Listed at the top of the Dev Resource Group under the name Darryl provided is an Organization ID . The Organization ID is an identifier used to identify Romanworks as a PACS Partner for federated identity purposes. Note: Note that this organization IS NOT the same as a client organization, which represents a group of installations. This is called out to avoid confusion later in training.
        • [YP Dev Portal: Integrations](https://developers.yonomi.cloud/getting-started/training-project/training-yp-developer-portal/training-create-a-dev-resource-group/dev-resource-groups-elements/integrations.md): First listed below the Dev Resource Group is the list of Integrations. Integrations are a relationship objects in Yonomi Platform that allows PACS Partners to establish & advertise their availability as a supported YP partner to owners and allow owners to choose a partner to manage their devices. Integrations allow partners to operate and manage devices on an owner’s behalf and receive and process device-related events. Note that Integrations - along with all other objects - are created as part and owned by the Dev Resource Group – as indicated in the left-side menu by the indention reflecting that ownership. Developer Portal objects do not exist outside of a Dev Resource Group. We’ll create integrations later in training.
        • [YP Dev Portal: Application Clients](https://developers.yonomi.cloud/getting-started/training-project/training-yp-developer-portal/training-create-a-dev-resource-group/dev-resource-groups-elements/yp-dev-portal-application-clients.md): Listed below Integrations are Application Clients. The Application clients section contains M2M and User Scope Clients. Application Clients request access to a protected Yonomi Platform resource on behalf of the Resource Owner, such as the Owner or the PACS Partner. In Yonomi Platform, clients allow Partners to generate JWT-based access tokens used for API Requests. We’ll create access tokens later in this training.
        • [YP Dev Portal: Webhooks](https://developers.yonomi.cloud/getting-started/training-project/training-yp-developer-portal/training-create-a-dev-resource-group/dev-resource-groups-elements/yp-dev-portal-webhooks.md): Listed below Application Clients are Webhooks. A Webhook is a service configuration in Yonomi Platform used to allow Yonomi Platform to send device and service-related events and data directly to PACS Partners for processing. Webhooks are means by which Yonomi Platform dispatches real-time device state changes and other event notifications to PACS Partners. PACS Partners create and configure webhooks in the YP Developer Portal as a component of a Dev Resource Group by supplying an API endpoint that will be used to capture data sent by Yonomi Platform anytime a device state changes, or any other event emits. We’ll create webhooks later in this training.
        • [YP Dev Portal : Federation Configurations](https://developers.yonomi.cloud/getting-started/training-project/training-yp-developer-portal/training-create-a-dev-resource-group/dev-resource-groups-elements/yp-dev-portal-federation-configurations.md): Listed below Webhooks are Federation Configurations. Federated Identity is a method of linking a user’s identity across multiple separate Identity Management Systems (IdMs). It allows users to quickly and reliably establish identity across systems while maintaining security. Yonomi Platform uses federated identity to allow PACS Partners to manage B-Y-O Identity for their clients/owners, integrators and other end users of their solutions. Configuring identify federation will allow Acme Living to be set up as a customer and allow Romanworks to provide apps to Acme Living that they can use to install and manage their hardware. Darryl will start his journey by configuring Identity Federated and create an account for Anna to use to set up her organization.
    • [Training: Create an Integration](https://developers.yonomi.cloud/getting-started/training-project/training-yp-developer-portal/training-create-an-integration.md): 5. Now that Darryl has a Dev Resource Group, he’ll need to configure his Yonomi Platform environment. The first step will be to create an Integration. As described earlier, an Integration is a relationship object in Yonomi Platform that allows PACS Partners to establish & advertise their availability as a supported YP partner to owners and allow owners to choose a partner to manage their devices. Integrations allow partners to operate and manage devices on an owner’s behalf and receive and process device-related events. While we do not yet have any installations for Acme, we can set up the prerequisites for managing installations now. To create an Integration: Click on the Integrations link in the Developer Portal menu, or click the Go to Integrations link from the main panel under the Integrations section. Next, Click the + Add Integration button. Populate the Name and Description fields For now, we’ll leave the Machine to Machine Credentials and Webhooks fields empty as we’ve not created those objects yet. We’ll come back later and populate those later. Be sure to click/check on the Make public radio box. This setting allows your integration to be queryable via API by owners such as Acme. Click the Create Integration button to create the integration.
    • [Training : Create an M2M Client](https://developers.yonomi.cloud/getting-started/training-project/training-yp-developer-portal/training-create-an-m2m-client.md): 6.Now that an Integration has been created, we can create an M2M Application Client . As you recall, M2M Clients are used to generate access tokens to build apps that PACS such as Romanworks themselves will use for device management and administration. We’ll use the Romanworks M2M Client to check device health, among other tasks. To create an M2M Client: Click on the Application Clients link from the menu Click on the + Add M2M Client button Fill the Name and Description fields. For the Integrations field click the dropdown and select the Integration you created in the previous step. Click the Create Machine to Machine Client button to create the M2M client.
    • [Training Create a Webhook Configuration](https://developers.yonomi.cloud/getting-started/training-project/training-yp-developer-portal/training-create-a-webhook-configuration.md): 7. Next, we’ll create a Webhook configuration. A Webhook is a service configuration used to allow Yonomi Platform to send device and service-related events and data directly to PACS Partners for processing. Creating a webhook is an involved, so we’ll use a prebuilt webhook for training. This webhook will capture events and output them to our shared Slack channel for training. To add a webhook config: Click on Webhooks in the left menu, then click on + Add Webhook Enter a name and description for your webhook configuration in the respective fields. For endpoint, use the following value: https://romanworks.romancontrols.com For event types, select all 4 events types ( Device State Updated , Device Action Updated , Device Action Created , Device Notification Reported ) For Integrations , select the Integration you created in the previous step. Click the Create Webhook Config button to complete creation of the webhook configuration.
    • [Training: Create an Identity Federation Configuration](https://developers.yonomi.cloud/getting-started/training-project/training-yp-developer-portal/training-create-an-identity-federation-configuration.md): Before creating Identity Federation Configurations, you must contact your Yonomi representative to request access to Federation Configs. 8. Before we can create a User Scope Application Client, we need to create a Federation Configuration . Recall that Federated Identity is a method of linking a user’s identity across multiple separate Identity Management Systems (IdMs). User Scope Clients are associated with users in the Identity Management System manage by the PACS Partner, so a User Scope Application Client cannot be created until Identity Federation is configured. Setting up an IdM and a Federated Identity is not a typical task developers perform, so we’ve set one up a training IdM to serve the purpose. The training IdM is not intended for use beyond training. To configure Identity Federation: Click Federation Config in the left-side menu Click the + Add Federation Config button Enter a relevant value for the Name (no spaces) and Description fields Enter the following value for Federation Discovery URL : https://romanworks-yp-dev1.us.auth0.com/wsfed/.well-known/openid-configuration Enter the following value for Federation Client ID : kLnObkjkR7MKhtQX9nEt1YWAzobb0rBw Set/Leave Connection Type as: Open ID Connect . Click the Create Federation Config button to complete federated identity configuration.
    • [Training: Create a User Scope Application Client](https://developers.yonomi.cloud/getting-started/training-project/training-yp-developer-portal/training-create-a-user-scope-application-client.md): 9. The last step in YP Dev Portal configuration we’ll cover for training is creating a User Scope Application Client. User Scope Clients are used to generate access tokens to build apps that a PACS Partner’s Clients/Owners, Integrators or Patrons will use to manage, monitor and operate devices. We’ll use a User Scope client to create an application that Acme Living Employees will use to manage their devices. To create a User Scope Client: Click on the Application Clients link from the menu Click on the + Add User Scope Client button Fill the Name and Description fields. Enter the following value for the Callback URLs field: https://services.yonomi.cloud Enter the following value for the Logout URLs field: https://services.yonomi.cloud Enter the following value for the Web Origin URLs field: https://services.yonomi.cloud For the Application Type field, select SPA to represent your client app as a single-page application. Note: These values will change for your own app and are only useful as set here for training purposes.
    • [Summary: YP Developer Portal](https://developers.yonomi.cloud/getting-started/training-project/training-yp-developer-portal/summary-yp-developer-portal.md): With creation of the User Scope Application Client, YP Developer Portal is complete. So far, we’ve created: A Dev Resource Group to manage YP Developer Portal Resources A Webhook Configuration for capturing events from YP A Federated Identity Configuration (Federation Config) to allow PACS to manage their end user customer identities A M2M Application Client that will be used to create access tokens that PACS Partners will use to integrate YP functionality with their own solutions and services A User Scope Application Client that will be used to create access tokens that PACS end users will use to create and manage installations and devices Next, we’ll move on to using the GraphQL API to create an Installation and get ready to add a devices for management.
  • [API Training Section 1: Working with th eYP GraphQL API](https://developers.yonomi.cloud/getting-started/training-project/api-training-section-1-working-with-th-eyp-graphql-api.md): Yonomi Platform uses a GraphQL-based API to expose its capabilities. GraphQL provides a schema that can be used to introspect available API queries (used to read data) and mutations (used to create, modify, or delete data). While the YP GraphQL Schema provides the complete specification of available requests, we’ll be using a Postman collection to exercise only a selection of queries and mutations for training. Please download the YP API Postman Training Collection at: https://yptraining.romancontrols.com
    • [Training: Using Postman for API Requests Part 1](https://developers.yonomi.cloud/getting-started/training-project/api-training-section-1-working-with-th-eyp-graphql-api/training-using-postman-for-api-requests-copy-1.md): The YP API Training Postman Collection includes requests we’ll follow to continue the training project. Requests are organized by folder based on the role we’ll be using to execute each. Requests are also enumerated for ordering purposes. Using the API, we’ll operate on behalf of the Romanworks PACS Partner for some of the requests and for others we’ll operate on behalf of Acme Living LLC . We’ll use different folders – and different access tokens – depending on who’s behalf the request will be executed. Title Description Operating as Acme Living, we will: Create an Organization Create an Installation Authorize the Acme Organization to be managed by the Romanworks public Integration so that Romanworks PACS can interact with Acme installations and devices For these requests we’ll use access tokens generated using the User Scope Application Client. Title Description Operating as Romanworks PACS we will: 4. Confirm Subscription to Acme Living Webhook Events 5. Query to confirm installation authorization For these requests we’ll use access tokens generated using M2M Application Client.
    • [Training: Generating Access Tokens using the Client Credential Client](https://developers.yonomi.cloud/getting-started/training-project/api-training-section-1-working-with-th-eyp-graphql-api/training-generating-access-tokens-using-the-client-credential-client.md): Acme Living will use User Scope Client-generated Access Tokens to interact with Yonomi Platform. Access Tokens generated using User Scope Application Clients require use one of the two OAuth2.0 Authorization Code grant types to obtain tokens. This grant type is used by web and mobile apps and requires an app to launch a browser to begin the flow to generate a token. At a high level, the flow has the following steps: The application opens a browser to send the user to the OAuth server The user sees the authorization prompt and approves the app’s request The user is redirected back to the application with an authorization code in the query string The application exchanges the authorization code for an access token This training will not focus on OAuth2.0 specifics – more on the OAuth2.0 Authorization Code grant type is available online . The Postman training collection is already set up to make it easy to obtain Client Credential Access Tokens. To obtain an access token: Open the Training collection in Postman Click on the Acme Living (Owner) API Operations collection to open it Click on the Authorization tab. Scroll the pane and notice the values are populated with variables. Click on the Variables tab to see the variables and representative values. Replace the following values with values from the Dev Resource Group created earlier in training: yp_auth_organization – This value is listed at the top of the Dev Resource Group owner_client_id – This value is listed as the Client ID in the Client Credential created earlier 6. Click the Save button to save the collection. 7. Return to the Authorization tab and scroll to the bottom of the screen 8. Click the Clear cookies button to ensure there are no credentials cached 9. Click the Get New Access Token button. This will launch a browser window that we’ll use to login and generate our token 10. Scroll to the bottom of the browser and click the Continue with [Romanworks] button to launch a federated identity authorization request. (This button will reflect whatever was entered in the Federated Identity name field) Note: Do not click the Continue button or attempt to log in with YP Developer Portal credentials. This flow is not intended to login as the developer. 11. On the next screen you’ll be presented with a similar login challenge. This time, click the Sign Up button to create a new account. This step will create an account representing an Owner. 12. Enter any valid email address and password and click Continue to create a new account to represent the account for an Acme Living Owner. Note: In a production setting this step would not be open for account creation; PACS will either have existing accounts created or integrate this flow with existing new user account creation activities. 13. Upon success, an access token will be generated and captured in Postman. Click the Use Token button to allow Postman to use this credential in API requests. Important : Note that these tokens expire within 10 minutes. To obtain a new token, follow the steps above but instead of creating a new account, simply log in with previously created credentials.
    • [Training: Generating Access Tokens using the M2M Client](https://developers.yonomi.cloud/getting-started/training-project/api-training-section-1-working-with-th-eyp-graphql-api/training-generating-access-tokens-using-the-m2m-client.md): Romanworks will use M2M Application Client-generated Access Tokens to interact with Yonomi Platform. Access Tokens generated using M2M Application Clients require use of the OAuth2.0 Client Credentials grant type to obtain tokens. This grant type flow is a server-to-server flow, where no user authentication is involved in the process. Access tokens generated using this grant type will not represent user identity, but instead contain a Client ID as the subject claim. At a high level, the flow has the following steps: The Client makes a POST request to the OAuth server The OAuth server issues the Access Token immediately and responds to the client This training will not focus on OAuth2.0 specifics – more on the OAuth2.0 Client Credentials grant type is available online . The Postman training collection is already set up to make it easy to obtain M2M Access Tokens. To obtain an access token: Open the Training collection in Postman Click on the Romanworks (PACS Partner) API Operations collection to open it Click on the Authorization tab. Scroll the pane and notice the values are populated with variables. Click on the Variables tab to see the variables and representative values. Replace the following values with values from the Dev Resource Group created earlier in training: yp_m2m_client_id – This value is listed as Client ID in the M2M Token Detail created earlier yp_m2m_client_secret – This value is listed as Client Secret in the M2M Token Detail created earlier 6. Click the Save button to save the collection. 7. Return to the Authorization tab and scroll to the bottom of the screen 8. Click the Clear cookies button to ensure there are no credentials cached 9. Click the Get New Access Token button. This will launch a browser window that we’ll use to login and generate our token 10. Upon success, an access token will be generated and captured in Postman. Click the Use Token button to allow Postman to use this credential in API requests. Important : Note that these tokens expire within 10 minutes. To obtain a new token, follow the steps above but instead of creating a new account, simply log in with previously created credentials.
    • [Training: Using Postman for API Requests Part 2](https://developers.yonomi.cloud/getting-started/training-project/api-training-section-1-working-with-th-eyp-graphql-api/training-using-postman-for-api-requests.md): The YP API Training Postman Collection includes requests we’ll follow to continue the training project. Requests are organized by folder based on the role we’ll be using to execute each. Requests are also enumerated for ordering purposes. Using the API, we’ll operate on behalf of the Romanworks PACS Partner for some of the requests and for others we’ll operate on behalf of Acme Living LLC . We’ll use different folders – and different access tokens – depending on who’s behalf the request will be executed. Title Description Operating as Acme Living, we'll execute API requests to: Create an Acme Living LLC Organization (Postman Request #2) Create an Installation for 125 Ocean Ave in Miami (Postman Request #5) Query the Romanworks (Public) Integration ID (Postman Request #8) Authorize the Romanworks Integration to manage the Acme Living Organization (Postman Request #9) Title Description Operating as Romanworks PACS we will: Process the webhook event sent upon authorization to confirm subscription for receiving Acme Living events Query to confirm the Romanworks Public Integration has authority to manage the Acme Living Organization
    • [Training: Create the Acme Living Organization (Request #2)](https://developers.yonomi.cloud/getting-started/training-project/api-training-section-1-working-with-th-eyp-graphql-api/training-create-the-acme-living-organization-request-2.md): For these steps we’re operating as Acme Living, LLC
      • [Sidequest: Observe the Scripts and Automatically Set Variables](https://developers.yonomi.cloud/getting-started/training-project/api-training-section-1-working-with-th-eyp-graphql-api/training-create-the-acme-living-organization-request-2/observe-the-scripts-and-automatically-set-variables.md): One of the reasons we train with Postman is because it allows us to automatically set variables that using scripts that run either before or after a request is made. Many of the calls we’ll make today will automatically set variables that will be used in future requests. If you’re wondering how a UUID was set such as organizationId , deviceId or one of the actionIDs captured in training, look at the Post-res Scripts for requests in training to understand where the variable value was established. For this collection, variables are set at the collection level , which means they can be found on the Variables tab of the top-level (Yonomi Platform PACS Training (collection) folder.
      • [Query the Romanworks Integration ID (Request #8)](https://developers.yonomi.cloud/getting-started/training-project/api-training-section-1-working-with-th-eyp-graphql-api/training-create-the-acme-living-organization-request-2/query-the-romanworks-integration-id-request-8.md): Note: This step is required to set the ID as a request variable for the next request.
      • [Authorize the Romanworks Integration to manage the Acme Org (Request #9)](https://developers.yonomi.cloud/getting-started/training-project/api-training-section-1-working-with-th-eyp-graphql-api/training-create-the-acme-living-organization-request-2/authorize-the-romanworks-integration-to-manage-the-acme-org-request-9.md): Note: At this step you will receive a webhook event. If you did not receive the event, confirm the Integration ID is properly set for this request and try again. Even if it appears to succeed (200 Response) it didn’t work if the Integration ID was mis-set.
    • [Training: Confirming the Webhooks Subscription](https://developers.yonomi.cloud/getting-started/training-project/api-training-section-1-working-with-th-eyp-graphql-api/training-confirming-the-webhooks-subscription.md): Next, we’ll switch identity and operate as Romanworks PACS
      • [The first webook event: A subscription confirmation request from YP](https://developers.yonomi.cloud/getting-started/training-project/api-training-section-1-working-with-th-eyp-graphql-api/training-confirming-the-webhooks-subscription/the-first-webook-event-a-subscription-confirmation-request-from-yp.md): "Message": "You have chosen to subscribe to the topic arn:aws:sns:…To confirm the subscription, visit the SubscribeURL included in this message." Run this request (GET) to confirm event subscription: The grantIntegrationAuthzToOrg request initiates dispatch of an event to the webhook configured that includes a URL we must load to confirm subscription of events for the Acme Living Organization. Any device, installation or organization related events will be pushed to the webhook following confirmation of subscription. In production this should happen automatically. In the previous steps we’ve successfully configured the Romanworks PACS Developer Portal and created the operational environment to begin working with Acme Living LLC. In the next section, we’ll move on to working with devices.
  • [Training: Preparation for Claiming a Device](https://developers.yonomi.cloud/getting-started/training-project/training-preparation-for-claiming-a-device.md): Now that we’ve successfully configured the Romanworks PACS Developer Portal and created the operational environment to begin working with Acme Living LLC, we can move on to working with devices. Our goal for this section is to claim a device, which will associate the device with Acme Living’s 125 Ocean Ave Installation. Title Description For this section we’ll be operating as an Integrator Ivonne, who is responsible for physical installation of devices at 125 Ocean Ave. In order to claim a device, we’ll need to follow these steps: Obtain and power a YP-enabled Allegion device (such as the Allegion XE360 WiFi lock) Configure the device to communicate over WiFi Obtain a claim token from the device Run the API request to claim the device against our installation Completing these steps requires building a mobile app that uses the Yonomi Platform Device Communication SDK to perform activities that include communicating with the device via BLE, enabling WiFi and sending commands to instruct the device to communicate with YP Platform. The Yonomi Platform Device Communication SDK is intended to be used by PACS Partners such as Romanworks to allow them to build required features into their own branded apps to achieve these tasks. Allegion provides an SDK version for both iOS and Android. Building an app is beyond the intended scope of this training, so we’ll be using a pre-built training app to complete these steps. The training app is not intended for production use! The app is also only available for Android (though as previously mentioned, SDKs are available for both iOS and Android). Note: This section requires Android Studio and having an Android mobile phone that can be tethered to the developer machine so the training app can be installed. For details on the Yonomi Platform Device Communication SDK and building these features into a PACS-provided app for integrators, visit the YP Developer Portal or the SDK Repositories.
    • [Training App](https://developers.yonomi.cloud/getting-started/training-project/training-preparation-for-claiming-a-device/download-the-training-app.md): To get the YP training app, browse to the following Github repository: https://github.com/Yonomi/yp-android-quickstart If not already downloaded, get Android Studio at: https://developer.android.com/studio Follow the instructions on the Training App Repo homepage to get the app running on an Android Phone. Note: This app will not work running from a simulator. Run the Training App Once the app is installed and running on an Android phone (not a simulator), follow these steps IN THE ORDER LISTED to prepare the device for claiming: Clone the Github project. Open the project in Visual Studio. Follow the directions in the Readme to update the details for your Github account, PAT Be sure to set the Auth0 domain information required for the app if yours are different from training defaults. Open the LogCat Dialog in Visual Studio Connect an Android phone to your computer Build the project. Run the project and open the app on your phone. Click the Register button to Register the mobile device. This step isn’t cached today in the app so it must occur for every load of the app. Click Obtain Claim Token to obtain a claim token. The claim token will be presented and provide an ability to copy it from the LogCat Copy the claim token to a place where it is accessible from the machine that will run postman API requests. Click Connect WiFi Network to search for WiFi. Enter the WiFi network details . Be sure you are connecting to a 2.4Ghz network . Click the Connect WiFi button. Await Success.
    • [Set the Claim Token in Postman](https://developers.yonomi.cloud/getting-started/training-project/training-preparation-for-claiming-a-device/set-the-claim-token-in-postman.md): Before attempting to run the mutation to claim a device, be sure to set the claim token in the postman collection variables tab: Open the postman collection Click on the Yonomi Platform PACS Training collection Click on the Variables tab to get to collection variables Scroll to the bottom to the claimToken variable Set the Current value of the variable to the value you obtained from the Training App in the previous section of training.
    • [Sidequest: How to FDR the XE360 WiFi Lock](https://developers.yonomi.cloud/getting-started/training-project/training-preparation-for-claiming-a-device/sidequest-how-to-fdr-the-xe360-wifi-lock.md): There may be a point where a device needs to be Factory-Device-Reset (FDR) for testing or other purposes. An FDR will reset some – but not all – lock settings. Perform an FDR with the following steps: Remove the device enclosure shell Press and hold the reset button for 7 seconds. The device will flash a light sequence then beep 3 times. Within 30 seconds of the last beep, turn the inside handle 3 times to complete an FDR. Devices that have been factory reset are not unclaimed and will reconnect to the same installation once reconnected to WiFi. Important : FDR DOES NOT result in unclaiming of a device. Devices will remain claimed beyond an FDR. Unclaiming is only achieved with an API Request to Yonomi Platform.
    • [Sidequest: Device Time](https://developers.yonomi.cloud/getting-started/training-project/training-preparation-for-claiming-a-device/sidequest-device-time.md): Keeping the device time accurate is an important requirement for XE360 and Yonomi Platform connected devices. PACS are NOT required to ensure time is set on a device; Allegion reduces the burden in the following ways: Time is set up first connection after power on automatically A periodic check-in is performed (either daily or weekly) Time is automatically set upon establishing a BLE connection using the YP Device Communication SDK Time Trait and the notification – infoDeviceTime – informs PACS when a device’s time has been updated.
  • [API Training Section 2: Claiming a Device](https://developers.yonomi.cloud/getting-started/training-project/api-training-section-2-claiming-a-device.md): Having obtained a claim token in the previous step and connecting the device to WiFi, we’re ready to claim the device. We’ll be returning to the Postman collection to complete this step. The access token used to run claim requests is generated using the User Scope Application Client, which is the same token type used by Acme Living LLC (the owner). Note, however, that we’ll create a new user in the IdM for the Integrator, Ivonne, to complete this step. Title Description Operating as the Integrator, we will: Claim the Device using the claim token Ivonne obtained in the previous section of training (Postman Request #11, Section 3) Query connected devices on the 125 Ocean Ave Installation (Postman Request #12, Section 3) Follow the ordered operations in the Postman Training Collection for the remainder of this section of training.
    • [Training: Set the Claim Token in Postman](https://developers.yonomi.cloud/getting-started/training-project/api-training-section-2-claiming-a-device/training-set-the-claim-token-in-postman.md): If you haven’t already, before attempting to run the mutation to claim a device, be sure to set the claim token in the postman collection variables tab: Open the postman collection Click on the Yonomi Platform PACS Training collection Click on the Variables tab to get to collection variables Scroll to the bottom to the claimToken variable Set the Current value of the variable to the value you obtained from the Training App in the previous section of training.
    • [Training: Claim a Device (Request #11)](https://developers.yonomi.cloud/getting-started/training-project/api-training-section-2-claiming-a-device/training-claim-a-device-request-11.md): Important: This request includes a header that is not used in previous requests. The x-allegion-installation-reference-id header is set to the value of the Acme Living installation ID. Turn Inside Handle, Get Events! Turn inside handle, receive events! We just turned the handle on the lock and witness a series of events be dispatched to the webhook endpoint. These events reflect the current and active state of all traits representing that device. This real-time release of events will occur for any change in device state, including changes to state related to device-based actuations such as lock handle turns, deadbolt thumb turns, battery depletion notifications, tamper events or other local activities. The number of events dispatched is dependent on the device capabilities and features. For instance, devices with more capabilities will have more traits for which to reflect state, and as a result a larger number of events will be dispatched to the webhook – one for each trait. A typical device will be represented by between roughly 10-20 traits . In the next section we’ll look at these events to understand their contents and what they convey about changing lock state.
  • [Training: Triggered Events](https://developers.yonomi.cloud/getting-started/training-project/training-triggered-events.md): Upon turning the inside handle, a series of events were dispatched to the webhook we set up. Let’s review those events, starting with a detailed review of one of the events to understand what data is generated for triggered actions such as manual turning of handles, battery events or other triggered notifications that are generated automatically.
    • [Training: Raw Event Data](https://developers.yonomi.cloud/getting-started/training-project/training-triggered-events/training-raw-event-data.md): Title Description Title Attribute Description Example Value Type Type of event received. Notification is the only value currently. "Type" : "Notification" MessageId A UUID uniquely identifying the event message. "MessageId" : "52615e1e-ba83-5087-a82e-01514139ef22" TopicARN This is the internal notification service topic used by Yonomi Platform tp publish the message. A topic is a logical access point that acts as a communication channel for the Amazon Simple Notification Service. YP uses Amazon SNS for pub/sub to provide message delivery from publishers to subscribers . This field is not relevant for partners. arn:aws:sns:us-east-1:078715503436:webhooks_installation_id_28f24e77-81e3-467e-b483-1e882bdcdd72 Message The JSON-based data about which the event is related. This value will include unique subfields depending on the nature of the event. This field is covered separately. Timestamp The timestamp of the event. This timestamp is based on UTC timezone. 2024-09-02T17:44:26.764Z Signature Amazon S3 signatures are used to authenticate requests made to Amazon S3 API services. Partners may use this field to authenticate messages from Yonomi Platform. ly2PV1UfCBb+V49rC2Rw2kt0kvypcjUeEG7Bo2/TfAPWsqdOxFHJ85QkvocMHKjmuJ6ySFVbQuAyilMH9fAW6FxVsqR82sTAPQ6SX6Qfqjic8HAZ5uB0OlB580jYtVz4ptRc7Y5HuDhNmg0sfWBNMmXtRIEgJhDM/LF7MxKqT6H0djWC1cz7dYlUfIc72Dv0Cq+kJ3ktzqfBGS7UUqbuKgSLqIlfMN7mw/Y9EX6phx5dYdyMkg7OJNi5oAy3D5PZGjVJikXt5AxFFHziPDlBwcvqbUP6FXdgtuTInfX2+8mAUGZB+CPYEbabt2H8CZh1syexWAgdn6W+1qJmJJm5qQ== SignatureVersion Identifies the version of AWS Signature that you want to support for authenticated requests. Partners may use this field to authenticate messages from Yonomi Platform. 1 SigningCertURL Points to the location of the X509 certificate used to create the digital signature for the message. Retrieve the certificate from this location. Partners may use this field to authenticate messages from Yonomi Platform https://sns.us-east-1.amazonaws.com/SimpleNotificationService-60eadc530605d63b8e62a523676ef735.pem UnsubscribeURL A URL that can be used to unsubscribe the endpoint from this topic. If this URL is visited, Amazon SNS unsubscribes the endpoint and stops sending notifications to this endpoint. https://sns.us-east-1.amazonaws.com/?Action=Unsubscribe&SubscriptionArn=arn:aws:sns:us-east-1:078715503436:webhooks_installation_id_28f24e77-81e3-467e-b483-1e882bdcdd72:5e5732a2-59ef-4f21-8060-187cbfd47bb3 MessageAttributes Attributes about the message sent. Most relevant data is event type. {"type" : {"Type":"String","Value":"DEVICE_NOTIFICATION_REPORTED"}}
    • [Training: The Message Field](https://developers.yonomi.cloud/getting-started/training-project/training-triggered-events/training-the-message-field.md): Title Description Title Attribute Description Example Value eventType Type of event. DEVICE_NOTIFICATION_REPORTED notifications Array container […] type Type of event in human readable format. notification reported category Category of event. Similar to type field notification createdAt Timestamp event was created 2024-09-02T17:44:26.669Z sampledAt If event represents data captured from device, timestamp event was sampled null installationId The Yonomi Platform installation UUID associated with this event 28f24e77-81e3-467e-b483-1e882bdcdd72 deviceId The YP device UUID associated with this event 6b6ba9ef-78e8-48c1-a5c2-3745b2518703 notificationName Name of the notification infoDeviceTime actionId The action UUID associated with this event null traitName Name of the trait associated with this message TimeZoneSettingsV1 notificationType Type of notification. Typically this will be INFO. INFO message A human-readable description of the subject and purpose of this message UTC Device time: 2021-02-19T00:16:11.000Z, Local Device time: 2021-02-19T00:16:11.000Z details Array container […] deviceTimeUtc Device Timestamp in UTC timezone 2021-02-19T00:16:11.000Z deviceTimeLocal Device Timestampe in device-local time 2021-02-19T00:16:11.000Z From here we can review other events dispatched to our webhook. Refer to the Slack channel used to capture events for training.
  • [API Training Section 3: Working with Devices](https://developers.yonomi.cloud/getting-started/training-project/api-training-section-3-working-with-devices.md): We’ve completed all steps necessary to get our lock at 125 Ocean Ave ready for use on Yonomi Platform. The lock is now addressable via API using its Device ID which was captured when we claimed the device. Now we can begin working with the device via the YP GraphQL API to configure it and make it ready and useable for Acme Living Tenants. By the end of this section, we’ll be able to use a plastic credential to unlock a lock. In this section we’ll focused on trait actions and webhook events, which work together to allow developers to build apps to manage devices and modify their state while providing visibility to changing device state, regardless of change source.
    • [Trait Actions and the Action Lifecycle](https://developers.yonomi.cloud/getting-started/training-project/api-training-section-3-working-with-devices/actions-and-the-yp-action-lifecycle.md): A Trait Action is an API request to Yonomi Platform to perform a device-related task. Examples of trait actions include claiming a device, uploading device firmware or updating a device configuration setting. Actions are performed by sending requests (in the form of GraphQL Mutations ) to the YP GraphQL API. Actions follow distinct lifecycles that can be completed in three ways : A single API call with synchronous resolution – does not have an action lifecycle Example: A single API call with asynchronous resolution – requires an action lifecycle management Example: A two-step upload process with asynchronous resolution – follows an action lifecycle Example: By understanding and following the appropriate action lifecycle for each flow, you can effectively manage and track actions within the platform. Let's explore each flow in detail.
    • [Single API Call with Synchrounous Resolution](https://developers.yonomi.cloud/getting-started/training-project/api-training-section-3-working-with-devices/api-calls/single-api-call-with-synchrounous-resolution.md): Title Description This flow applies to all developer and user related actions, organization and installation creation and device claiming/un-claiming. For this type of action, YP expects to receive the GraphQL mutation name along with the required or optional arguments. The selection set should be derived from the specific mutation documentation.
    • [Single API Call with Asynchrounous Resolution](https://developers.yonomi.cloud/getting-started/training-project/api-training-section-3-working-with-devices/api-calls/single-api-call-with-asynchrounous-resolution.md): Title Description All trait-defined actions that manipulate a device's state after it has been claimed fall under this flow except bulk data uploads. When invoking a single API call with asynchronous resolution, the mutation name and the necessary arguments should be provided. The selection set should include the Action ID to track the action's lifecycle effectively. There are two relevant events are associated with this flow: DEVICE_ACTION_CREATE and DEVICE_ACTION_UPDATED
    • [Two-step Bulk Upload Process with Asynchrounous Resolution](https://developers.yonomi.cloud/getting-started/training-project/api-training-section-3-working-with-devices/api-calls/two-step-bulk-upload-process-with-asynchrounous-resolution.md): Title Description This flow is used for bulk data uploads within Yonomi Platform. The two-step bulk upload process involves completely rewriting a device’s data record for a specific trait when the action is resolved. Therefore, instead of uploading only the data that needs to be modified, the entire desired data record/representation should be uploaded. This ensures that the updating data is accurately reflected and replaces the existing data within the trait. The process begins with a request for an upload URL, which returns a pre-signed URL or an expected return URL. Upon a successful action, a DEVICE_ACTION_CREATED event is logged, and a webhook event is emitted. The action status at this point is awaiting_data . Once the file upload is completed, a DEVICE_ACTION_UPDATED event is logged, and a webhook event is emitted with status set to pending. When the device completes the action, a DEVICE_ACTION_UPDATED event is generated, and a webhook event is emitted with the status set to resolved.
    • [Events in Yonomi Platform](https://developers.yonomi.cloud/getting-started/training-project/api-training-section-3-working-with-devices/events-in-yonomi-platform.md): Event logs are data emitted and temporarily stored as a result of activity in Yonomi Platform. Yonomi Platform generates 2 types of event data: Action Lifecycle Event Logs These events are emitted for any asynchronous action performed in YP. This includes Atomic Actions and Bulk Upload Actions. Synchronous actions do not follow the Action Lifecycle and so event logs are not generated for synchronous actions. Device History Event Logs These events are emitted whenever device state changes. By leveraging these event logs, you can gain insights into the action lifecycle and device history. These events provide valuable information for monitoring, tracking, and analyzing the behavior and changes within the YP platform. All the events that are queryable using the event log are also emitted via webhook. It is advised that the developers use the data from webhook in favor of querying the event log to maintain service availability if/when rate limiting is implemented.
      • [Action-Lifecycle Events](https://developers.yonomi.cloud/getting-started/training-project/api-training-section-3-working-with-devices/events-in-yonomi-platform/action-lifecycle-events.md): Two event types are associated with the action lifecycle: DEVICE_ACTION_CREATED and DEVICE_ACTION_UPDATED DeviceActionCreatedEvent Schema: Plain text … on DeviceActionCreatedEvent { eventType createdAt actionId deviceId status traitName actionParameters } DeviceActionUpdatedEvent Schema: Plain text … on DeviceActionUpdatedEvent { eventType createdAt actionId deviceId status }
      • [Device History Events](https://developers.yonomi.cloud/getting-started/training-project/api-training-section-3-working-with-devices/events-in-yonomi-platform/device-history-events.md): Device history is captured through three types of events: DEVICE_STATE_UPDATED, DEVICE_BULK_DATE_STATE_UPDATED, and DEVICE_NOTIFICATION_REPORTED DEVICE_STATE_UPDATED Schema: Plain text ... on DeviceStateUpdatedEvent { eventType createdAt deviceId fieldName traitName value } DEVICE_BULK_DATE_STATE_UPDATED Schema: Plain text ... on DeviceBulkDataStateUpdatedEvent { eventType deviceId createdAt traitName url } DEVICE_NOTIFICATION_REPORTED Schema: Plain text .. on DeviceNotificationReportedEvent { eventType deviceId notificationName notificationType message sampledAt createdAt traitName } The DEVICE_STATE_UPDATED and DEVICE_BULK_DATE_STATE_UPDATED events report changes in device states as defined in the trait design. These events capture state updates and bulk state updates, respectively. The time the event took place on the device is not available for these events. The DEVICE_NOTIFICATION_REPORTED event reports more transient changes on a device. Notifications within this event are categorized as either info or warning, similar to audits and alerts. The time these events took place in the device is expected to be available.
    • [Training: Working with Devices](https://developers.yonomi.cloud/getting-started/training-project/api-training-section-3-working-with-devices/training-working-with-devices.md): We already reviewed the 3 Trait Action types: Single API Call Actions with synchronous resolution lifecycle – resolved by API response. Single API Call Actions with asynchronous resolution lifecycle – resolved by webhook event Two-Step Upload Actions with asynchronous resolution lifecycle – resolved by webhook event We’ll execute actions and process the webhook events we receive upon making action requests. In the Device Query section we will perform the following: Query to list claimed devices Query some of the traits of a device including battery trait, lock status, device display details Execute Single API Calls with Asynchronous Resolution: Set the Lock Display Name & Get Status by Action ID (webhook event, API request) Set Auto-Relock Setting Get Lock Credentials and Schedules (Returns URL) Execute a Two-Step API Call with Asynchronous Resolution: Set Credentials & Schedules, Step 1: Get the Upload URL Get Status of the request- see AWAITING DATA for action status Set Credentials & Schedules, Step 2: Upload JSON Payload Get Status of Action Request to Upload JSON (confirm action succeeded) Get Lock Credentials & Schedules Again (Confirm change) Finally, Test your Credential! Understanding Traits and Trait Actions is key to managing devices on Yonomi Platform. Trait Actions are the mechanism Yonomi Platform supports to modify the state of a device. Examples of modifying device state include changing a property such as a device’s display name, adding credentials and schedules or increasing auto-lock timer settings. Trait Actions will use one of the 3 lifecycle patterns described earlier in training. Trait Actions operate on the traits – or behaviors and properties – exposed on a device. Note that trait actions – implemented as GraphQL mutations - are different than queries, which only read device state. The next section provides a summary of the different Trait Actions available, the Traits on which they operate, and the lifecycle pattern used to support action interactions. We’ll use many of them through the remainder of training.
    • [Device Queries](https://developers.yonomi.cloud/getting-started/training-project/api-training-section-3-working-with-devices/device-queries.md): For these steps we’re operating as Acme Living, LLC Requests in this section require the x-allegion-installation-reference-id header Listing Claimed Devices (Request #12) Get Device Traits (Request #13) Notice this query returns only the names of all trait fields but no other details. That’s because this is how request was formulated. We can expand the information returned in the query by building a more detailed request – but you have to know what’s available to do that. GraphQL makes that easy with Schema Introspection . Using Schema Introspection, developers can build queries using the Postman IDEs GraphQL interface, which evaluates the schema and returns valid values for the schema request type. We’ll spend 5-10 minutes using the Postman GraphQL Schema Introspection tool to learn how to add more detail to this request. Sidequest: GraphQL Introspection The Postman Collection contains a folder called GraphQL API Schema (Generic Introspection), created to make it easy to use Postman’s GraphQL point-and-click interface to build and execute queries. After generating an access token on the Authorization tab, Use the Yonomi Platform GraphQL Endpoint object to navigate the schema and select the fields you want in a query. This approach makes it easy to explore the entire set of Queries and Mutations available in Yonomi Platform and create and save queries and mutations. Get Lock Status Traits (Request #14)
    • [Device Actions: Examples of Single API Calls with Asynchrounous Resolution](https://developers.yonomi.cloud/getting-started/training-project/api-training-section-3-working-with-devices/device-actions-examples-of-single-api-calls-with-asynchrounous-resolution.md): Action! Toggle Lock Status! (Request #15) The lockStatus trait action provides a way to change the actuating state of the lock latch. Setting the lockStatus state attribute to TOGGLE (one of the enum options) will actuate the lock latching mechanism to either unlocked (if the lock is currently locked) or locked (if the lock is currently unlocked). Send the request. You will hear the lock audibly actuate. Now, turn the outside lock handle to confirm the lock status is opposite what it was before you sent the request. Send the request again to confirm your success. Notice the Action ID returned in the response body. For this request we only need hear the change occur to know it was successful, but for future requests we’ll look at the action event by its Action ID. Action! Set Lock Display Name (Request #16) The setDisplayName trait action allows us to change the display name of the lock. This is the name that will advertise over BLE for the lock when scanning. (When testing, be sure to restart any apps and disable/enable BLE before scanning.) For this request we’ll look at the resolution of the response in two different ways: We’ll look for at webhook events for a relevant event with matching action ID, event type of DEVICE_ACTION_UPDATED event with a status of ‘ RESOLVED ’. We’ll query (poll) the status of all events with a matching action ID and identify if one exists with event type DEVICE_ACTION_UPDATED event and status of ‘ RESOLVED ’. Important: Polling is not a best practice for your application. Polling implemented in a production app will not meet certification standards.
    • [Trait Action Resolution: Webhooks vs. Event Queries](https://developers.yonomi.cloud/getting-started/training-project/api-training-section-3-working-with-devices/trait-action-resolution-webhooks-vs-event-queries.md): Process Set Display Name Action Response (Webhook) Webhooks are the best practice way to track and capture disposition status of a trait action request. Our training webhook is set up to capture details and report them to Slack for easy search and viewing. To find the status of the request sent for training: Go to the Yonomi Workspace Slack channel to which used for capturing our webhooks Search for the Action ID from the previous request in the search bar Click on the latest message record found, which will be at the top of the list Review the message to find the actionStatus property. It will be set to RESOLVED for a successful request. If the search does not yield multiple records for the action ID, your request was not sent successfully, you did not subscribe to receive DEVICE_ACTION_UPDATED events or the lock is offline. Reconnect the lock to WiFi and events will be sent; no need to resend the action request. Historical Events/Polling: Query Result by Action ID (Request #17) You can also get the status of the request using the GraphQL API. Run the “Get Status of Action Request to Set Display Name (using Action ID)” request to get the status of the last trait action request we made. Note it reports the same detail as what was captured in webhook. If the response to this request is empty it likely means one of the following: This request was not successfully sent (Unauthorized) You did not subscribe to receive DEVICE_ACTION_UPDATED events The lock is offline. Reconnect the lock to WiFi and events will be sent; no need to resend the action request. Sidequest: Disconnect WiFi and Test Actions, Notifications When a lock is disconnected, all trait action requests to a device - as well as notifications from a device – are queued for processing and dispatch once the device has reconnected to WiFi. You can test this by: Manually disconnecting WiFi Sending a new action request (to queue an event) and/or turning a lock inside handle (to queue lock notifications) Reconnecting WiFi Performing this test will not require a power cycle to reconnect a device to WiFi in production (Q2 2025)... But it might during our beta period. Action! Set Auto-Lock Setting, Get Action Status (Request #18, 19) Action! Get Credentials & Schedules (Request #20) The response for this request will include a URL that links to the JSON formatted credentials and schedules payload for the lock . Click on the URL from within postman to generate a new postman request. Action! Get Credentials & Schedules ( GET results from previous request) Run this newly-generated request ( GET .). The response will be an empty JSON Payload representing a lock with no credentials or schedules set. Next, we’ll use a 2-step action to set a credential in a lock along with a schedule so that we can operate the lock with a physical (or mobile) credential. No need to save this request; it’s a snapshot in time that tells the state of the lock’s credentials and settings as the locks reports it right now.
    • [Device Actions: Examples of 2-Step API Calls with Asynchronous Resolution](https://developers.yonomi.cloud/getting-started/training-project/api-training-section-3-working-with-devices/device-actions-examples-of-2-step-api-calls-with-asynchronous-resolution.md): 2-Step Action! Set Credentials and Schedules! Step 1a: Get Upload URL (Request #21) The Upload URL is the endpoint developers will use to update a device’s complete credentials and schedules “database”. The Upload URL - obtain from the response to this request - will be automatically populated by a script that we’ll use in the second step of this call to upload our credentials and schedules JSON Payload. Step 1b: Get Status of Action ID (Request #22) We’re pausing here to observe the state of our action request before we initiate the second step of this request. Here we are looking up the Action by the Action ID. Notice the status of the action is “ AWAITING_DATA ” Sidequest: Getting a Credential ID Observe that the JSON definition for the credential MUST adhere to the following rules: Must be in All CAPS and Hexadecimal Must be 32 characters Must be appended by a series of Fs for empty characters Step 2 : Upload Credential Data (JSON) (Request #23) This is the second step of the 2-step process we initiated with request #21 to obtain an Upload URL In this step we use a PUT to upload a JSON payload (the body of this request) to the URL we obtained in Step 1. We’ll receive a 200 status response with an empty status response. The 200 indicates that our request was successfully sent, but it does not mean it was successfully processed. We will wait about 2 minutes and then, once again, query the status of our request (same as the previous call we just made) to observe the acknowledgement of the change in state. Step 2 (completed): Get Status of Action ID once again (Request #24) After letting the request process, we see the action request was successfully resolved. Notice the status of the action is “ RESOLVED ”. If you get a status of “REJECTED”, obviously something when wrong. Check the JSON payload for malformed JSON. If you make this request too early, you’ll only see a record with status of “PENDING”, so be patient if that’s what you see, then send the request again. Note: We actually received 2 DEVICE_ACTION_UPDATED requests returned – one for the action when it change from AWAITING_DATA to PENDING and another when it changed from PENDING to RESOLVED . Good Measure! Get Credentials & Schedules Once Again (Request #25) This request is a duplicate of #20, used to GET the credentials and schedules as established by the device. This confirms that the credential was successfully applied to the device.