Engage Service Commands

The Engage Service uses the Publish Method (attached to EventTypeInfo) to interact with its respective hardware.

Please observe the examples of how to use the service commands. The examples assume you have already set up the appropriate object to use for the object link. However the objects used are named to correspond to the type of object that is meant to be linked.

AppKey Namespace
EngageServiceCommands EngageServiceCommands

The available commands for this service are presented below:

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://keepapi.feenicshosting.com/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://keepapi.feenicshosting.com/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://keepapi.feenicshosting.com/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://keepapi.feenicshosting.com/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://keepapi.feenicshosting.com/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://keepapi.feenicshosting.com/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://keepapi.feenicshosting.com/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://keepapi.feenicshosting.com/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://keepapi.feenicshosting.com/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="
}'