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:
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="
}'
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="
}'
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="
}'
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="
}'
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="
}'
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="
}'
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=="
}'
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="
}'
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="
}'