LDAP Service Commands

Send commands to the LDAP synchronization service through the acre platform’s event-driven architecture. These commands enable management of directory synchronization operations, including forcing re-synchronization and bulk deletion of imported records.

Overview

The LDAP Service processes commands published via the event messaging system. Commands are sent to LDAP Agents that manage Active Directory or LDAP-compatible directory synchronization.

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

Command Categories

Category Commands Description
Synchronization Re-Sync Query Force full synchronization from directory
Cleanup Delete Records Remove all records imported by a query
Relation Object Type Description
LdapQuery LdapQueryInfo Directory search/sync query
LdapAgent LdapAgentInfo LDAP synchronization agent

Prerequisites

Before sending commands:

  1. Agent Running - Verify the LDAP Agent is online and connected
  2. Query Active - The target query must be active on the running agent
  3. Object References - Have valid keys for both query and agent objects
  4. Permissions - User must have Publish permission on the command EventType

⚠️ Warning: Delete Command

The ldap:queryDeleteRecords command permanently removes all records found by the specified query. Use extreme caution:

  • This includes all persons imported via DirSync
  • Verify the query scope before executing
  • Consider testing on a non-production instance first
  • This action cannot be undone

Synchronization Commands

Re-Sync a Query

Command Nickname Object Links Parameters
Re-Sync A Query ldap:queryReSyncRecords LdapQuery,LdapAgent NONE

This Command initializes the attached LDAP Query that is active on the running Agent to commence a full Synchronization of all records from what was its initial state.

Re-Sync a Query

Example in C#

await client.PublishEventAsync(currentInstance,
	"LdapService",
	new MonikerItem {Namespace = "LdapServiceEvents", Nickname = "ldap:queryReSyncRecords"}, 
	DateTime.UtcNow, 
    new {},
    ldapQuery.AsObjectLink("LdapQuery"), 
	ldapAgent.AsObjectLink("LdapAgent")
);

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-28T16:46:24.5691777Z",
  "AppKey": "LdapService",
  "EventTypeMoniker": {
    "$type": "Feenics.Keep.WebApi.Model.MonikerItem, Feenics.Keep.WebApi.Model",
    "Namespace": "LdapServiceEvents",
    "Nickname": "ldap:queryReSyncRecords"
  },
  "RelatedObjects": [
    {
      "$type": "Feenics.Keep.WebApi.Model.ObjectLinkItem, Feenics.Keep.WebApi.Model",
      "Href": "/api/f/INSTANCE.KEY/ldapqueries/LDAPQUERY.KEY",
      "LinkedObjectKey": "LDAPQUERY.KEY",
      "CommonName": "DirSyncLDAP",
      "Relation": "LdapQuery",
      "MetaDataBson": null
    },
    {
      "$type": "Feenics.Keep.WebApi.Model.ObjectLinkItem, Feenics.Keep.WebApi.Model",
      "Href": "/api/f/INSTANCE.KEY/ldapagents/LDAPAGENT.KEY",
      "LinkedObjectKey": "LDAPAGENT.KEY",
      "CommonName": "LDAP Agent",
      "Relation": "LdapAgent",
      "MetaDataBson": null
    }
  ],
  "EventDataBsonBase64": "BQAAAAA="
}'

Delete All Items In A Query

Command Nickname Object Links Parameters
Delete all items in a Query ldap:queryDeleteRecords LdapQuery,LdapAgent NONE

⚠️ CAUTION: This command should be used with extreme caution. Be sure you are executing this command on an LDAP Query that will only find the items you wish to delete. If using DirSync, all Active Directory imported persons will be removed from Keep.

Delete all items in a Query

Example in C#

await client.PublishEventAsync(currentInstance,
	"LdapService",
	new MonikerItem {Namespace = "LdapServiceEvents", Nickname = "ldap:queryDeleteRecords"}, 
	DateTime.UtcNow, 
    new {},
    ldapQuery.AsObjectLink("LdapQuery"), 
	ldapAgent.AsObjectLink("LdapAgent")
);

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-28T16:46:24.5691777Z",
  "AppKey": "LdapService",
  "EventTypeMoniker": {
    "$type": "Feenics.Keep.WebApi.Model.MonikerItem, Feenics.Keep.WebApi.Model",
    "Namespace": "LdapServiceEvents",
    "Nickname": "ldap:queryDeleteRecords"
  },
  "RelatedObjects": [
    {
      "$type": "Feenics.Keep.WebApi.Model.ObjectLinkItem, Feenics.Keep.WebApi.Model",
      "Href": "/api/f/INSTANCE.KEY/ldapqueries/LDAPQUERY.KEY",
      "LinkedObjectKey": "LDAPQUERY.KEY",
      "CommonName": "DirSyncLDAP",
      "Relation": "LdapQuery",
      "MetaDataBson": null
    },
    {
      "$type": "Feenics.Keep.WebApi.Model.ObjectLinkItem, Feenics.Keep.WebApi.Model",
      "Href": "/api/f/INSTANCE.KEY/ldapagents/LDAPAGENT.KEY",
      "LinkedObjectKey": "LDAPAGENT.KEY",
      "CommonName": "LDAP Agent",
      "Relation": "LdapAgent",
      "MetaDataBson": null
    }
  ],
  "EventDataBsonBase64": "BQAAAAA="
}'

Best Practices

Practice Description
Test First Test delete commands on non-production instances
Verify Query Scope Review what records the query will affect before deletion
Use Re-Sync Sparingly Full re-syncs can be resource-intensive for large directories
Monitor Events Subscribe to events to track synchronization progress
Document Changes Log when manual sync commands are issued

Troubleshooting

Issue Cause Solution
Command ignored Agent offline Verify LDAP Agent is running and connected
Query not found Invalid query key Verify LdapQuery object key is correct
No records synced Query scope issue Check query filter and directory connectivity
Sync incomplete Directory timeout Check network connectivity to directory server