Engage Service Commands

Send commands to Schlage Engage wireless locks and gateways through the acre platform’s event-driven architecture. These commands enable real-time control of wireless locks for unlock, secure, pulse, and status operations.

Overview

The Engage Service processes commands published via the event messaging system. Commands are sent to Engage IP Gateways which then relay them to connected wireless locks.

Property Value
AppKey EngageServiceCommands
Namespace EngageServiceCommands
Method PublishEventAsync()
Endpoint /api/f/{instance}/eventmessagesink

Command Categories

Category Commands Description
Status Get Status Request gateway and lock status
Lock Control Pulse, Unlock, Secure Real-time lock operations
Relation Object Type Description
EngageGateway EngageIPGatewayInfo Wireless gateway/hub
Reader EngageReaderInfo Wireless lock device

Command Behavior Notes

Behavior Description
Caching Most commands (except Pulse) are cached by the gateway if the lock is offline
Pulse Timing Pulse duration uses the Re-lock time configured on the EngageReaderInfo
Event Response Lock state changes generate “Lock State Override Event at {Reader} - {State}”
Status Update Get Status updates the Status property on gateways and locks

Lock State Values

State Description
Secure Lock is in secured/locked state
Passage Lock is in unlocked/passage state
Timed Unlock Lock is temporarily unlocked (pulse)

Prerequisites

Before sending commands:

  1. Gateway Online - Verify the Engage IP Gateway is connected
  2. Lock Status - Check lock connectivity before sending Pulse commands
  3. Object References - Have valid keys for gateway and reader objects
  4. Permissions - User must have Publish permission on the command EventType

Lock Control Commands

Get Hardware Status

Command Nickname Object Links Parameters
Get Hardware Status engage-command:getStatus Engage IP Gateway NONE

This command is used to request an updated status of the Gateway and its linked Gateways.

A “Hardware Status Changed” event will be published for the Gateway and its locks. The Status property for each of them will also be updated.

Get Hardware Status

Example in C#

await client.PublishEventAsync(folder, "EngageServiceCommands", new MonikerItem
{
        Namespace = "EngageServiceCommands",
        Nickname = "engage-command:getStatus"
}, DateTime.UtcNow, new { }, gateway.AsObjectLink("EngageGateway"));

Example in CURL

curl -X POST \
  https://api.us.acresecurity.cloud/api/f/INSTANCE.KEY/eventmessagesink\
  -H 'Authorization:  Bearer TOKEN_GOES_HERE' \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache' \
  -d '{
	"$type":"Feenics.Keep.WebApi.Model.EventMessagePosting, Feenics.Keep.WebApi.Model",
	"OccurredOn":"2019-01-28T14:26:25.0501636Z",
	"AppKey":"EngageServiceCommands",
	"EventTypeMoniker":
	{
		"$type":"Feenics.Keep.WebApi.Model.MonikerItem, Feenics.Keep.WebApi.Model",
		"Namespace":"EngageServiceCommands",
		"Nickname":"engage-command:getStatus"
	},
	"RelatedObjects":
	[
		{
			"$type":"Feenics.Keep.WebApi.Model.ObjectLinkItem, Feenics.Keep.WebApi.Model",
			"Href":"/api/f/INSTANCE.KEY/engageipgateways/ENGAGEIPGATEWAY.KEY",
			"LinkedObjectKey":"ENGAGEIPGATEWAY.KEY",
			"CommonName":"NotARealGateway",
			"Relation":"EngageGateway",
			"MetaDataBson":null
		}
	],
	"EventDataBsonBase64":"BQAAAAA="
}'

Pulse Reader

Command Nickname Object Links Parameters
Pulse Reader engage-command:pulse Engage IP Gateway,Engage Reader NONE

This command is used to Momentarily unlock a lock. The unlock time is equivalent to the Re-lock time on the EngageReaderInfo. Note: The Gateway will not cache this command if the lock is not online. Check the status of the lock to determine its connectivity.

If the lock is online, then the lock will unlock then secure. An Event will be generated by the lock “Lock State Override Event at {Reader} - {State}” Where State is “Timed Unlock”.

Pulse Reader

Example in C#


await client.PublishEventAsync(folder, "EngageServiceCommands", new MonikerItem
{
        Namespace = "EngageServiceCommands",
        Nickname = "engage-command:pulse"
}, DateTime.UtcNow, new { }, gateway.AsObjectLink("EngageGateway"), reader.AsObjectLink("Reader"));

Example in CURL

curl -X POST \
  https://api.us.acresecurity.cloud/api/f/INSTANCE.KEY/eventmessagesink \
  -H 'Authorization:  Bearer TOKEN_GOES_HERE' \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache' \
  -d '{
	"$type":"Feenics.Keep.WebApi.Model.EventMessagePosting, Feenics.Keep.WebApi.Model",
	"OccurredOn":"2019-01-28T14:26:25.0501636Z",
	"AppKey":"EngageServiceCommands",
	"EventTypeMoniker":
	{
		"$type":"Feenics.Keep.WebApi.Model.MonikerItem, Feenics.Keep.WebApi.Model",
		"Namespace":"EngageServiceCommands",
		"Nickname":"engage-command:pulse"
	},
	"RelatedObjects":
	[
       {
            "$type":"Feenics.Keep.WebApi.Model.ObjectLinkItem, Feenics.Keep.WebApi.Model",
            "Href":"/api/f/INSTANCE.KEY/peripherals/READER.KEY",
            "LinkedObjectKey":"READER.KEY",
            "CommonName":"ReaderExampleForCurl",
            "Relation":"Reader",
            "MetaDataBson":null
       },
		{
			"$type":"Feenics.Keep.WebApi.Model.ObjectLinkItem, Feenics.Keep.WebApi.Model",
			"Href":"/api/f/INSTANCE.KEY/engageipgateways/ENGAGEIPGATEWAY.KEY",
			"LinkedObjectKey":"ENGAGEIPGATEWAY.KEY",
			"CommonName":"NotARealGateway",
			"Relation":"EngageGateway",
			"MetaDataBson":null
		}
	],
	"EventDataBsonBase64":"BQAAAAA="
}'

Secure Reader

Command Nickname Object Links Parameters
Secure Reader engage-command:secure Engage IP Gateway,Engage Reader NONE

This command is used to Secure a lock. Note: The Gateway will cache this command if the lock is not online. When the lock becomes online, the gateway will send the command down.

If the lock is online, then the lock will transition to Secure or stay secure. An Event will be generated by the lock “Lock State Override Event at {Reader} - {State}” Where State is “Secure”.

Secure Reader

Example in C#


await client.PublishEventAsync(folder, "EngageServiceCommands", new MonikerItem
{
        Namespace = "EngageServiceCommands",
        Nickname = "engage-command:secure"
}, DateTime.UtcNow, new { }, gateway.AsObjectLink("EngageGateway"), reader.AsObjectLink("Reader"));

Example in CURL

curl -X POST \
  https://api.us.acresecurity.cloud/api/f/INSTANCE.KEY/eventmessagesink \
  -H 'Authorization:  Bearer TOKEN_GOES_HERE' \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache' \
  -d '{
	"$type":"Feenics.Keep.WebApi.Model.EventMessagePosting, Feenics.Keep.WebApi.Model",
	"OccurredOn":"2019-01-28T14:26:25.0501636Z",
	"AppKey":"EngageServiceCommands",
	"EventTypeMoniker":
	{
		"$type":"Feenics.Keep.WebApi.Model.MonikerItem, Feenics.Keep.WebApi.Model",
		"Namespace":"EngageServiceCommands",
		"Nickname":"engage-command:secure"
	},
	"RelatedObjects":
	[
       {
            "$type":"Feenics.Keep.WebApi.Model.ObjectLinkItem, Feenics.Keep.WebApi.Model",
            "Href":"/api/f/INSTANCE.KEY/peripherals/READER.KEY",
            "LinkedObjectKey":"READER.KEY",
            "CommonName":"ReaderExampleForCurl",
            "Relation":"Reader",
            "MetaDataBson":null
       },
		{
			"$type":"Feenics.Keep.WebApi.Model.ObjectLinkItem, Feenics.Keep.WebApi.Model",
			"Href":"/api/f/INSTANCE.KEY/engageipgateways/ENGAGEIPGATEWAY.KEY",
			"LinkedObjectKey":"ENGAGEIPGATEWAY.KEY",
			"CommonName":"NotARealGateway",
			"Relation":"EngageGateway",
			"MetaDataBson":null
		}
	],
	"EventDataBsonBase64":"BQAAAAA="
}'

Unlock Reader

Command Nickname Object Links Parameters
Unlock Reader engage-command:unlock Engage IP Gateway,Engage Reader NONE

This command is used to unlock a lock. Note: The Gateway will cache this command if the lock is not online. When the lock becomes online, the gateway will send the command down.

If the lock is online, then the lock will transition to Unlock (Passage) or stay secure. An Event will be generated by the lock “Lock State Override Event at {Reader} - {State}” Where State is “Passage”.

Unlock Reader

Example in C#

await client.PublishEventAsync(folder, "EngageServiceCommands", new MonikerItem
{
        Namespace = "EngageServiceCommands",
        Nickname = "engage-command:unlock"
}, DateTime.UtcNow, new { }, gateway.AsObjectLink("EngageGateway"), reader.AsObjectLink("Reader"));

Example in CURL

curl -X POST \
  https://api.us.acresecurity.cloud/api/f/INSTANCE.KEY/eventmessagesink \
  -H 'Authorization:  Bearer TOKEN_GOES_HERE' \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache' \
  -d '{
	"$type":"Feenics.Keep.WebApi.Model.EventMessagePosting, Feenics.Keep.WebApi.Model",
	"OccurredOn":"2019-01-28T14:26:25.0501636Z",
	"AppKey":"EngageServiceCommands",
	"EventTypeMoniker":
	{
		"$type":"Feenics.Keep.WebApi.Model.MonikerItem, Feenics.Keep.WebApi.Model",
		"Namespace":"EngageServiceCommands",
		"Nickname":"engage-command:unlock"
	},
	"RelatedObjects":
	[
       {
            "$type":"Feenics.Keep.WebApi.Model.ObjectLinkItem, Feenics.Keep.WebApi.Model",
            "Href":"/api/f/INSTANCE.KEY/peripherals/READER.KEY",
            "LinkedObjectKey":"READER.KEY",
            "CommonName":"ReaderExampleForCurl",
            "Relation":"Reader",
            "MetaDataBson":null
       },
		{
			"$type":"Feenics.Keep.WebApi.Model.ObjectLinkItem, Feenics.Keep.WebApi.Model",
			"Href":"/api/f/INSTANCE.KEY/engageipgateways/ENGAGEIPGATEWAY.KEY",
			"LinkedObjectKey":"ENGAGEIPGATEWAY.KEY",
			"CommonName":"NotARealGateway",
			"Relation":"EngageGateway",
			"MetaDataBson":null
		}
	],
	"EventDataBsonBase64":"BQAAAAA="
}'

Scan For Locks

Command Nickname Object Links Parameters
Scan For Locks engage-command:scan Engage IP Gateway NONE

This command is used to Scan for nearby locks. This command must be sent before adding EngageReaderInfo to a gateway. The gateway will not link a lock if it does not have it in its latest scan list.

After receiving the command, the service will send the command to the Gateway. It will publish an event “Gateway Scan Started” to indicate that a scan has started. If the scan succeeds, the service will publish an event “Gateway Scan Finished”. The Event Data will list the discovered locks. See the example the expected Event Data listed with the call.

If there are no locks advertising, then the the ScanList will not have any locks in the body. If the scan fails, the an Event “Gateway Scan Failed” will be published. Inspect the body of the event to learn about what cause the scan to fail.

Scan For Locks

Example in C#


await client.PublishEventAsync(folder, "EngageServiceCommands", new MonikerItem
{
        Namespace = "EngageServiceCommands",
        Nickname = "engage-command:scan"
}, DateTime.UtcNow, new { }, gateway.AsObjectLink("EngageGateway"));

//Example of Expected Event Data
{  
   "ScanResult":{  
      "Lock1":{  
         "MainSn":"0000000000000000",
         "DeviceName":"NDE Lock",
         "SignalQuality":"Med",
         "ModelType":"nde"
      }
   }
}

//Possible Reason for Failure will display like this
{  
   "Message":"Linked devices at maximum"
}

Example in CURL

curl -X POST \
  https://api.us.acresecurity.cloud/api/f/INSTANCE.KEY/eventmessagesink \
  -H 'Authorization:  Bearer TOKEN_GOES_HERE' \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache' \
  -d '{
	"$type":"Feenics.Keep.WebApi.Model.EventMessagePosting, Feenics.Keep.WebApi.Model",
	"OccurredOn":"2019-01-28T14:26:25.0501636Z",
	"AppKey":"EngageServiceCommands",
	"EventTypeMoniker":
	{
		"$type":"Feenics.Keep.WebApi.Model.MonikerItem, Feenics.Keep.WebApi.Model",
		"Namespace":"EngageServiceCommands",
		"Nickname":"engage-command:scan"
	},
	"RelatedObjects":
	[
		{
			"$type":"Feenics.Keep.WebApi.Model.ObjectLinkItem, Feenics.Keep.WebApi.Model",
			"Href":"/api/f/INSTANCE.KEY/engageipgateways/ENGAGEIPGATEWAY.KEY",
			"LinkedObjectKey":"ENGAGEIPGATEWAY.KEY",
			"CommonName":"NotARealGateway",
			"Relation":"EngageGateway",
			"MetaDataBson":null
		}
	],
	"EventDataBsonBase64":"BQAAAAA="
}'

Update Gateway Firmware

Command Nickname Object Links Parameters
Update Gateway Firmware engage-command:updateGateway Engage IP Gateway EventData -FirmwareUrl: string(url),DownloadTime: string(UTCDateTime),ApplyTime: string(UTCDateTime)(Note: The DownloadTime and ApplyTime can be omitted. If omitted, the Gateway will dowanlod and apply the update immediately. If supplied, these times are treated as UTC times. To get the list of the available firmware files, use the api call “api/f/{folderId}/engagefirmwarespec/gwe”)

This command is used to update the Gateway Firmware.

The Gateway status will indicate that it is updating the firmware. After the update, the Gateway Version will be updated.

Update Gateway Firmware

Example in C#

await client.PublishEventAsync(folder, "EngageServiceCommands", new MonikerItem
{
        Namespace = "EngageServiceCommands",
        Nickname = "engage-command:updateGateway"
}, DateTime.UtcNow, new {  
     FirmwareUrl="https://URLTODOWNLOAD",
     DownloadTime= "2018-05-10T19:40:11.7579812Z",
     ApplyTime="2018-05-10T19:40:11.7579812Z"
   }, 
   gateway.AsObjectLink("EngageGateway"));

Example in CURL

curl -X POST \
  https://api.us.acresecurity.cloud/api/f/INSTANCE.KEY/eventmessagesink\
  -H 'Authorization:  Bearer TOKEN_GOES_HERE' \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache' \
  -d '{
	"$type":"Feenics.Keep.WebApi.Model.EventMessagePosting, Feenics.Keep.WebApi.Model",
	"OccurredOn":"2019-01-28T14:26:25.0501636Z",
	"AppKey":"EngageServiceCommands",
	"EventTypeMoniker":
	{
		"$type":"Feenics.Keep.WebApi.Model.MonikerItem, Feenics.Keep.WebApi.Model",
		"Namespace":"EngageServiceCommands",
		"Nickname":"engage-command:updateGateway"
	},
	"RelatedObjects":
	[
		{
			"$type":"Feenics.Keep.WebApi.Model.ObjectLinkItem, Feenics.Keep.WebApi.Model",
			"Href":"/api/f/INSTANCE.KEY/engageipgateways/ENGAGEIPGATEWAY.KEY",
			"LinkedObjectKey":"ENGAGEIPGATEWAY.KEY",
			"CommonName":"NotARealGateway",
			"Relation":"EngageGateway",
			"MetaDataBson":null
		}
	],
	"EventDataBsonBase64":"hgAAAAJGaXJtd2FyZVVybAAVAAAAaHR0cDovL1VSTFRPRE9XTkxPQUQAAkRvd25sb2FkVGltZQAdAAAAMjAxOC0wNS0xMFQxOTo0MDoxMS43NTc5ODEyWgACQXBwbHlUaW1lAB0AAAAyMDE4LTA1LTEwVDE5OjQwOjExLjc1Nzk4MTJaAAA="
}'

Update Reader Firmware

Command Nickname Object Links Parameters
Update Readers Firmware engage-command:updateReader Engage IP Gateway EventData -FirmwareUrl: string(url),DeviceType: string,FirmwareVersion: string(“x.x.x”),DownloadTime: string(UTCDateTime),ApplyTime: string(UTCDateTime)(Note: The DownloadTime and ApplyTime can be omitted. If omitted, the Gateway will dowanlod and apply the update immediately. If supplied, these times are treated as UTC times. To get the list of the available firmware files, use the api call “api/f/{folderId}/engagefirmwarespec/{deviceType}” where deviceType is nde/le/be476/fe410.)

This command is used to update the Locks Firmware for a specific type.

After the update, the lock Version will be updated.

Update Readers Firmware

Example in C#

await client.PublishEventAsync(folder, "EngageServiceCommands", new MonikerItem
{
        Namespace = "EngageServiceCommands",
        Nickname = "engage-command:updateReader"
}, DateTime.UtcNow, new
{  
   FirmwareUrl = "https://URLTODOWNLOAD",
   DeviceType = "nde",//For NDE, For le specify le, for control specify be467 of fe410
   FirmwareVersion = "x.x.x",
   DownloadTime = "2018-05-10T19:40:11.7579812Z",
   ApplyTime ="2018-05-10T19:40:11.7579812Z"
}
   ApplyTime="2018-05-10T19:40:11.7579812Z"
}, gateway.AsObjectLink("EngageGateway"));

Example in CURL

curl -X POST \
  https://api.us.acresecurity.cloud/api/f/INSTANCE.KEY/eventmessagesink \
  -H 'Authorization:  Bearer TOKEN_GOES_HERE' \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache' \
  -d '{
	"$type":"Feenics.Keep.WebApi.Model.EventMessagePosting, Feenics.Keep.WebApi.Model",
	"OccurredOn":"2019-01-28T14:26:25.0501636Z",
	"AppKey":"EngageServiceCommands",
	"EventTypeMoniker":
	{
		"$type":"Feenics.Keep.WebApi.Model.MonikerItem, Feenics.Keep.WebApi.Model",
		"Namespace":"EngageServiceCommands",
		"Nickname":"engage-command:updateReader"
	},
	"RelatedObjects":
	[
		{
			"$type":"Feenics.Keep.WebApi.Model.ObjectLinkItem, Feenics.Keep.WebApi.Model",
			"Href":"/api/f/INSTANCE.KEY/engageipgateways/ENGAGEIPGATEWAY.KEY",
			"LinkedObjectKey":"ENGAGEIPGATEWAY.KEY",
			"CommonName":"NotARealGateway",
			"Relation":"EngageGateway",
			"MetaDataBson":null
		}
	],
	"EventDataBsonBase64":"tQAAAAJGaXJtd2FyZVVybAAVAAAAaHR0cDovL1VSTFRPRE9XTkxPQUQAAkRldmljZVR5cGUABAAAAG5kZQACRmlybXdhcmVWZXJzaW9uAAYAAAB4LngueAACRG93bmxvYWRUaW1lAB0AAAAyMDE4LTA1LTEwVDE5OjQwOjExLjc1Nzk4MTJaAAJBcHBseVRpbWUAHQAAADIwMTgtMDUtMTBUMTk6NDA6MTEuNzU3OTgxMloAAA=="
}'

Clear and Reload Cards

Command Nickname Object Links Parameters
Clear And Reload Cards engage-command:clearAndReloadCards Engage IP Gateway,Engage Reader NONE

This command is used to resync the Lock Card database. It will clear and reload all the cards. Depending on the number of cards to push, this operation may take a long time. An event “Door File Updated” will be published by the lock after it finishes downloading and processing the cards.

An event “Door File Updated” will be published by the lock after it finishes downloading and processing the cards.

Clear And Reload Cards

Example in C#


await client.PublishEventAsync(folder, "EngageServiceCommands", new MonikerItem
{
        Namespace = "EngageServiceCommands",
        Nickname = "engage-command:clearAndReloadCards"
}, DateTime.UtcNow, new { }, gateway.AsObjectLink("EngageGateway"), reader.AsObjectLink("Reader"));

Example in CURL

curl -X POST \
  https://api.us.acresecurity.cloud/api/f/INSTANCE.KEY/eventmessagesink\
  -H 'Authorization:  Bearer TOKEN_GOES_HERE' \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache' \
  -d '{
	"$type":"Feenics.Keep.WebApi.Model.EventMessagePosting, Feenics.Keep.WebApi.Model",
	"OccurredOn":"2019-01-28T14:26:25.0501636Z",
	"AppKey":"EngageServiceCommands",
	"EventTypeMoniker":
	{
		"$type":"Feenics.Keep.WebApi.Model.MonikerItem, Feenics.Keep.WebApi.Model",
		"Namespace":"EngageServiceCommands",
		"Nickname":"engage-command:unlock"
	},
	"RelatedObjects":
	[
       {
            "$type":"Feenics.Keep.WebApi.Model.ObjectLinkItem, Feenics.Keep.WebApi.Model",
            "Href":"/api/f/INSTANCE.KEY/peripherals/READER.KEY",
            "LinkedObjectKey":"READER.KEY",
            "CommonName":"ReaderExampleForCurl",
            "Relation":"Reader",
            "MetaDataBson":null
       },
		{
			"$type":"Feenics.Keep.WebApi.Model.ObjectLinkItem, Feenics.Keep.WebApi.Model",
			"Href":"/api/f/INSTANCE.KEY/engageipgateways/ENGAGEIPGATEWAY.KEY",
			"LinkedObjectKey":"ENGAGEIPGATEWAY.KEY",
			"CommonName":"NotARealGateway",
			"Relation":"EngageGateway",
			"MetaDataBson":null
		}
	],
	"EventDataBsonBase64":"BQAAAAA="
}'

Sync Gateway

Command Nickname Object Links Parameters
Sync Gateway engage-command:sync Engage IP Gateway NONE

This command is used to unlink locks that are linked to the gateway but are not in the Object links.

Sync Gateway

Example in C#


await client.PublishEventAsync(folder, "EngageServiceCommands", new MonikerItem
{
        Namespace = "EngageServiceCommands",
        Nickname = "engage-command:sync"
}, DateTime.UtcNow, new {}, gateway.AsObjectLink("EngageGateway"));

Example in CURL

curl -X POST \
  https://api.us.acresecurity.cloud/api/f/INSTANCE.KEY/eventmessagesink%20HTTP/1.1 \
  -H 'Authorization:  Bearer TOKEN_GOES_HERE' \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache' \
  -d '{
	"$type":"Feenics.Keep.WebApi.Model.EventMessagePosting, Feenics.Keep.WebApi.Model",
	"OccurredOn":"2019-01-28T14:26:25.0501636Z",
	"AppKey":"EngageServiceCommands",
	"EventTypeMoniker":
	{
		"$type":"Feenics.Keep.WebApi.Model.MonikerItem, Feenics.Keep.WebApi.Model",
		"Namespace":"EngageServiceCommands",
		"Nickname":"engage-command:sync"
	},
	"RelatedObjects":
	[
		{
			"$type":"Feenics.Keep.WebApi.Model.ObjectLinkItem, Feenics.Keep.WebApi.Model",
			"Href":"/api/f/INSTANCE.KEY/engageipgateways/ENGAGEIPGATEWAY.KEY",
			"LinkedObjectKey":"ENGAGEIPGATEWAY.KEY",
			"CommonName":"NotARealGateway",
			"Relation":"EngageGateway",
			"MetaDataBson":null
		}
	],
	"EventDataBsonBase64":"BQAAAAA="
}'