Components All New MacOS Windows Linux iOS
Examples Mac & Win Server Client Guides Statistic FMM Blog Deprecated Old

LDAP.AddJSON

Adds an entry to a tree.

Component Version macOS Windows Linux Server iOS SDK
LDAP JSON 8.0 ✅ Yes ✅ Yes ✅ Yes ✅ Yes ❌ No
MBS( "LDAP.AddJSON"; LDAPRef; dn; JSON )   More

Parameters

Parameter Description Example
LDAPRef The reference number for the LDAP connection. $ldap
dn The name of the entry to add.
JSON The JSON to parse.
Must be a JSON array with entries. Each entry has an element operation with Add, Replace, Delete or Increment. Also a node with name "type" and the type to set. Than you can pass with value a single value or with values a list of values.

Result

Returns OK or error.

Description

Adds an entry to a tree.
The parent of the entry being added must already exist or the parent must be empty (equal to the root distinguished name) for an add operation to succeed.

Sample JSON for structure:

[{
    "operation": "Add",
    "type": "xxx",
    "values": ["Hello", "World"]
},
{
    "operation": "Add",
    "type": "yyy",
    "base64": true,
    "value": "SGVsbG8gV29ybGQ="
},
{
    "operation": "Add",
    "type": "zzz",
    "hex": true,
    "value": "48656C6C6F20576F726C64"
}]

Type is the name of the attribute, e.g. cn.
Version 10.1 or newer accepts name instead of type for the key to match the search results.

Version 10.3 adds new boolean fields "hex" and "base64". If true, we decode value from hex/base64 encoding and pass them as binary values.

Examples

Add a new employee to LDAP:

Set Variable [ $ldap ; Value: MBS("LDAP.Connect"; "ldap.test.de"; 0; 389 ) ]
Set Variable [ $r ; Value: MBS("LDAP.Bind"; $ldap; "cn=admin,dc=ldap,dc=test,dc=de"; "S2A2S@home"; "simple" ) ]
Set Variable [ $r ; Value: MBS("LDAP.AddJSON"; $ldap; Employee::_LDAP.Entry.CN; Employee::_LDAP.JSON.Add) ]
Set Variable [ $r ; Value: MBS("LDAP.Release"; $ldap) ]

Example result:
Input JSON used:
[
  {
    "operation":   "Add",
    "name":   "objectClass",
    "values":   [
      "posixAccount",
      "shadowAccount",
      "top",
      "inetOrgPerson",
      "organizationalPerson",
      "person"
    ]
  },
  {
    "operation":   "Add",
    "name":   "uid",
    "value":   "bob.miller"
  },
  {
    "operation":   "Add",
    "name":   "uidNumber",
    "value":   "1"
  },
  {
    "operation":   "Add",
    "name":   "cn",
    "value":   "Bob Miller"
  },
  {
    "operation":   "Add",
    "name":   "mail",
    "value":   "bob.miller@test.de"
  },
  {
    "operation":   "Add",
    "name":   "homeDirectory",
    "value":   "/usr/local/var/"
  },
  {
    "operation":   "Add",
    "name":   "sn",
    "value":   "Miller"
  },
  {
    "operation":   "Add",
    "name":   "employeeType",
    "value":   "Employee"
  },
  {
    "operation":   "Add",
    "name":   "givenName",
    "value":   "Bob"
  },
  {
    "operation":   "Add",
    "name":   "employeeNumber",
    "value":   "77"
  },
  {
    "operation":   "Add",
    "name":   "userPassword",
    "value":   "xxxx"
  },
  {
    "operation":   "Add",
    "name":   "gidNumber",
    "value":   "100"
  }
]

Example script to create new group:

# ========================================
# Purpose:
# Creates a new AD Group
# Returns:
# $error = Error code if unsuccessful
# $error = 0 for success
# $resultText = Text summary of the success or error
# Parameters:
# $serverName
# $serverDomain
# $baseOU
# $groupName (base name only, excluding domain name)
# $groupDomain
# Called from:
# (script) "Set AD Group (worker)"
# Author:
# John Munro (HJM) from Deutsche Schule Tokyo Yokohama
# Notes:
# none
# History:
# 2021-05-26 HJM - created from DySIS-StudentAdmin version
# ========================================
#
Set Variable [ $! ; Value: #Assign ( Get ( ScriptParameter ) ) ]
#
# The branch in LDAP containing all active entries
Set Variable [ $searchBase ; Value: "dc=dsty,dc=ac,dc=jp" ]
#
Set Error Capture [ On ]
#
# If debugging these parameters will be empty so fill with test data
If [ $serverName = "" ]
    Set Variable [ $serverName ; Value: "sn-sys-dc1" ]
End If
If [ $serverDomain = "" ]
    Set Variable [ $serverDomain ; Value: "schulnetz.dsty.ac.jp" ]
End If
If [ $baseOU = "" ]
    Set Variable [ $baseOU ; Value: $searchBase ]
End If
If [ $groupName = "" ]
    Set Variable [ $groupName ; Value: "Test-Group" ]
End If
If [ $groupDomain = "" ]
    Set Variable [ $groupDomain ; Value: "dsty.ac.jp" ]
End If
#
#
# Bind to LDAP
Perform Script [ Specified: From list ; “LDAPServerBind” ; Parameter: # ( "serverName" ; $serverName ) & # ( "serverDomain" ; $serverDomain ) ]
# Returns $result, $ldap
#
Set Variable [ $! ; Value: #Assign ( Get ( ScriptResult ) ) ]
If [ $error <> 0 ]
    Show Custom Dialog [ "LDAP error" ; $resultText ]
    Exit Script [ Text Result: # ( "error" ; $result ) & # ( "resultText" ; "LDAP error: " & $resultText ) ]
End If
#
#
# Sanity check: Ensure that group is not already present in AD
Set Variable [ $LDAPFilter ; Value: "(sAMAccountName=" & $groupName & ")" ]
Set Variable [ $result ; Value: MBS ( "LDAP.Search" ; $ldap ; $searchBase ; "subtree" ; $LDAPFilter ; "" ; 0 ; 20 ; 9999 ) ]
#
Set Variable [ $entryCount ; Value: MBS("LDAP.SearchResult.Count"; $ldap) ]
If [ $entryCount > 0 ]
    # The group is already present in AD so exit with error
    Set Variable [ $resultText ; Value: "The sAMAccountName is already present in AD: \" & $groupName" ]
    Show Custom Dialog [ "LDAP Error" ; $resultText ]
    # Cleanup
    Set Variable [ $releaseResult ; Value: MBS("LDAP.Release"; $ldap) ]
    Exit Script [ Text Result: # ( "error" ; 1 ) & # ( "resultText" ; "LDAP error: " & $resultText ) ]
End If
#
#
# Sanity check: Ensure the DN is not already present in AD
Set Variable [ $groupDN ; Value: "CN=" & $groupName & "," & $baseOU ]
Set Variable [ $LDAPFilter ; Value: "" ]
Set Variable [ $result ; Value: MBS ( "LDAP.Search" ; $ldap ; $groupDN ; "base" ; $LDAPFilter ; "" ; 0 ; 4 ; 1 ) ]
#
Set Variable [ $entryCount ; Value: MBS("LDAP.SearchResult.Count"; $ldap) ]
If [ $entryCount > 0 ]
    # The groupname is already present in AD so exit with error
    Set Variable [ $resultText ; Value: "The DN is already present in AD: " & $groupDN ]
    Show Custom Dialog [ "LDAP Error" ; $resultText ]
    # Cleanup
    Set Variable [ $releaseResult ; Value: MBS("LDAP.Release"; $ldap) ]
    Exit Script [ Text Result: # ( "error" ; 1 ) & # ( "resultText" ; "LDAP error: " & $resultText ) ]
End If
#
#
# ===============================================================================================
# Group is confirmed not present in AD so proceed to create it
# Build the JSON for the Add
#
# AD attributes
Set Variable [ $objectClass ; Value: "{ \"operation\": \"Add\", \"name\": \"objectClass\", \"values\": [ \"top\", \"group\" ] }" ]
Set Variable [ $sAMAccountName ; Value: "{ \"operation\": \"Add\", \"name\": \"sAMAccountName\", \"value\": \"" & $groupName & "\" }" ]
Set Variable [ $cn ; Value: "{ \"operation\": \"Add\", \"name\": \"cn\", \"value\": \"" & $groupName & "\" }" ]
Set Variable [ $mail ; Value: "{ \"operation\": \"Add\", \"name\": \"mail\", \"value\": \"" & Lower ( $groupName & "@" & $groupDomain ) & "\" }" ]
#
# Add the JSON components together
Set Variable [ $json ; Value: "[" & $objectClass & "," & $sAMAccountName & "," & $cn & "," & $mail & "]" ]
#
# Attempt to add the groupDN record to the $baseOU
Set Variable [ $result ; Value: MBS( "LDAP.AddJSON" ; $ldap ; $groupDN ; $json ) ]
If [ MBS( "IsError" ) ]
    Set Variable [ $resultText ; Value: "Failed to add group." & ¶ & $result & ¶ & $json ]
    Show Custom Dialog [ "LDAP Error" ; $resultText ]
    # Cleanup
    Set Variable [ $releaseResult ; Value: MBS("LDAP.Release"; $ldap) ]
    Exit Script [ Text Result: # ( "error" ; $result ) & # ( "resultText" ; "LDAP error: " & $resultText ) ]
End If
#
#
# Cleanup
Set Variable [ $releaseResult ; Value: MBS("LDAP.Release"; $ldap) ]
Go to Layout [ original layout ; Animation: None ]
#
#
# Return error free result
Exit Script [ Text Result: # ( "error" ; 0 ) & # ( "resultText" ; "Group create success" ) ]

Example script to create an user:

# ========================================
# Purpose:
# If the user is not present in AD, create a new user in Pre-handover OU and add the groups defined in DySIS
# Returns:
# 0 for success
# Errot text if unsuccessful
# Parameters:
# $serverName
# $userName
# $userDomain
# $userEmail
# $fullName
# $surname
# $givenName
# $userOU
# $groups (base names only, excluding domain names)
# $userPassword
# Called from:
# (script) Create AD User account
# Author:
# John Munro (HJM) from Deutsche Schule Tokyo Yokohama
# Notes:
# none
# History:
# 2020-06-30 HJM - created
# 2020-09-10 HJM - modified to add parameter $userOU
# 2020-12-18 HJM - modified PasswordSet to use external subroutine rather than local code
# 2021-05-20 HJM - Replaced bind code with call to LDAPServerBind (including added parameter $serverDomain to all calls)
# ========================================
#
Set Variable [ $! ; Value: #Assign ( Get ( ScriptParameter ) ) ]
#
# ===============================================================================================
# If debugging these parameters will be empty so fill with test data
If [ $serverName = "" ]
    Set Variable [ $serverName ; Value: "sys-dc1" ]
End If
If [ $serverName = "" ]
    Set Variable [ $serverDomain ; Value: "dsty.ac.jp" ]
End If
If [ $userName = "" ]
    Set Variable [ $userName ; Value: "DySIStestUser" ]
End If
If [ $userDomain = "" ]
    Set Variable [ $userDomain ; Value: "dsty.ac.jp" ]
End If
If [ $userEmail = "" ]
    Set Variable [ $userEmail ; Value: "dysistestUser@dsty.test" ]
End If
If [ $userPassword = "" ]
    Set Variable [ $userPassword ; Value: "Welcome2" ]
End If
If [ $fullName = "" ]
    Set Variable [ $fullName ; Value: "DySIS testUser" ]
End If
If [ $surname = "" ]
    Set Variable [ $surname ; Value: "testUser" ]
End If
If [ $givenName = "" ]
    Set Variable [ $givenName ; Value: "DySIStest" ]
End If
If [ $userOU = "" ]
    Set Variable [ $userOU ; Value: "OU=Pre-handover,OU=DSTY Groups,DC=dsty,DC=ac,DC=jp" ]
End If
# Note $groups as an empty set is a valid condition so this should NOT be filled if empty
#
#
# Bind to LDAP
Perform Script [ Specified: From list ; “LDAPServerBind” ; Parameter: # ( "serverName" ; $serverName ) & # ( "serverDomain" ; $serverDomain ) ]
# Returns $error,$resultText, $ldap
#
Set Variable [ $! ; Value: #Assign ( Get ( ScriptResult ) ) ]
If [ $error <> 0 ]
    Go to Layout [ original layout ; Animation: None ]
    Show Custom Dialog [ "LDAP error" ; $resultText ]
    Exit Script [ Text Result: # ( "error" ; $error ) & # ( "resultText" ; "LDAP error: " & $resultText ) ]
End If
#
#
# Sanity check: Ensure that user is not already present in AD
#
Set Variable [ $LDAPFilter ; Value: "(sAMAccountName=" & $userName & ")" ]
Set Variable [ $result ; Value: MBS ( "LDAP.Search" ; $ldap ; $searchBase ; "subtree" ; $LDAPFilter ; "" ; 0 ; 20 ; 9999 ) ]
#
Set Variable [ $entryCount ; Value: MBS("LDAP.SearchResult.Count"; $ldap) ]
If [ $entryCount > 0 ]
    # The username is already present in AD so exit with error
    Set Variable [ $errorText ; Value: "The sAMAccountName is already present in AD: \" & $userName" ]
    Show Custom Dialog [ "LDAP Error" ; $errorText ]
    # Cleanup
    Set Variable [ $releaseResult ; Value: MBS("LDAP.Release"; $ldap) ]
    Exit Script [ Text Result: "LDAP error. " & $errorText ]
End If
#
# Sanity check: Ensure the DN is not already present in AD
#
Set Variable [ $personDN ; Value: "CN=" & $fullName & "," & $userOU ]
Set Variable [ $LDAPFilter ; Value: "" ]
Set Variable [ $result ; Value: MBS ( "LDAP.Search" ; $ldap ; $personDN ; "base" ; $LDAPFilter ; "" ; 0 ; 4 ; 1 ) ]
#
Set Variable [ $entryCount ; Value: MBS("LDAP.SearchResult.Count"; $ldap) ]
If [ $entryCount > 0 ]
    # The username is already present in AD so exit with error
    Set Variable [ $errorText ; Value: "The DN is already present in AD: " & $personDN ]
    Show Custom Dialog [ "LDAP Error" ; $errorText ]
    # Cleanup
    Set Variable [ $releaseResult ; Value: MBS("LDAP.Release"; $ldap) ]
    Exit Script [ Text Result: "LDAP error. " & $errorText ]
End If
#
#
# ===============================================================================================
# User is confirmed not present in AD so proceed to create it
# Build the JSON for the Add
#
# AD attributes
Set Variable [ $objectClass ; Value: "{ \"operation\": \"Add\", \"name\": \"objectClass\", \"values\": [ \"top\", \"person\", \"organizationalPerson\", \"user\" ] }" ]
Set Variable [ $sAMAccountName ; Value: "{ \"operation\": \"Add\", \"name\": \"sAMAccountName\", \"value\": \"" & $userName & "\" }" ]
Set Variable [ $userPrincipalName ; Value: "{ \"operation\": \"Add\", \"name\": \"userPrincipalName\", \"value\": \"" & $userName & "@" & $userDomain & "\" }" ]
Set Variable [ $userAccountControl ; Value: "{ \"operation\": \"Add\", \"name\": \"userAccountControl\", \"value\": \"" & 544 & "\" }" //NB: 544 is [ NoPasswordRequired, NormalAccount ] ]
Set Variable [ $cn ; Value: "{ \"operation\": \"Add\", \"name\": \"cn\", \"value\": \"" & $fullName & "\" }" ]
Set Variable [ $displayName ; Value: "{ \"operation\": \"Add\", \"name\": \"displayName\", \"value\": \"" & $fullName & "\" }" ]
Set Variable [ $sn ; Value: "{ \"operation\": \"Add\", \"name\": \"sn\", \"value\": \"" & $surname & "\" }" ]
Set Variable [ $givenName ; Value: "{ \"operation\": \"Add\", \"name\": \"givenName\", \"value\": \"" & $givenName & "\" }" ]
Set Variable [ $mail ; Value: "{ \"operation\": \"Add\", \"name\": \"mail\", \"value\": \"" & $userEmail & "\" }" ]
#
# Add the JSON components together
Set Variable [ $json ; Value: "[" & $objectClass & "," & $sAMAccountName & "," & $userPrincipalName & "," & $userAccountControl & "," & $cn & "," & $displayName & "," & $sn & "," & $givenName & "," & $mail & "]" ]
#
# Attempt to add the personDN record to the default OU
Set Variable [ $result ; Value: MBS( "LDAP.AddJSON" ; $ldap ; $personDN ; $json ) ]
If [ MBS( "IsError" ) ]
    Set Variable [ $errorText ; Value: "Failed to add user." & ¶ & $result & ¶ & $json ]
    Show Custom Dialog [ "LDAP Error" ; $errorText ]
    # Cleanup
    Set Variable [ $releaseResult ; Value: MBS("LDAP.Release"; $ldap) ]
    Exit Script [ Text Result: "LDAP error. " & $errorText ]
End If
#
# ===============================================================================================
# Set the password
#
Perform Script [ Specified: From list ; “Set AD Password (worker)” ; Parameter: # ( "serverName" ; $serverName ) & # ( "serverDomain" ; $serverDomain ) & # ( "personDN" ; $personDN ) & # ( "userPassword" ; $userPassword ) ]
#
Set Variable [ $result ; Value: Get ( ScriptResult ) ]
If [ $result <> 0 ]
    Show Custom Dialog [ "Error setting the password" ; $result ]
    # Exit with failure
    Exit Script [ Text Result: "Error setting the password:¶" & $result ]
End If
#
#
# ===============================================================================================
# Set the userAccountControl to NormalAccount (512)
# Prior to setting the password, the account has a password not required attribute
#
# Build the JSON for the modify
Set Variable [ $json ; Value: "[{ \"operation\": \"Replace\", \"name\": \"userAccountControl\", \"value\": \"512\" }]" ]
#
# Attempt to modify the groupDN record
Set Variable [ $result ; Value: MBS( "LDAP.ModifyJSON" ; $ldap ; $personDN ; $json ) ]
If [ MBS( "IsError" ) ]
    Set Variable [ $errorText ; Value: "Failed to set account to 'Normal account (type 512)'." & ¶ & $result & ¶ & $json ]
    Show Custom Dialog [ "LDAP Error" ; $errorText ]
    # Cleanup
    Set Variable [ $releaseResult ; Value: MBS("LDAP.Release"; $ldap) ]
    Exit Script [ Text Result: "LDAP error. " & $errorText ]
End If
#
#
# Cleanup
Set Variable [ $releaseResult ; Value: MBS("LDAP.Release"; $ldap) ]
#
#
# ===============================================================================================
# Add the person to all the groups passed in $groups
#
Set Variable [ $groupDomain ; Value: $userDomain ]
#
Set Variable [ $groupIndex ; Value: 1 ]
Set Variable [ $groupCount ; Value: ValueCount ( $groups ) ]
If [ $groupCount > 0 ]
    #
    Loop
        Set Variable [ $groupName ; Value: GetValue ( $groups ; $groupIndex ) ]
        #
        If [ $groupName <> "" ]
            #
            # This worker script is already running on the server so do not nest it to a sub server script as this does not make sense nor work.
            Perform Script [ Specified: From list ; “Set AD Group (worker)” ; Parameter: # ( "serverName" ; $serverName ) & # ( "serverDomain" ; $serverDomain ) & # ( "operation" ; "Add" ) & # ( "personDN" ; $personDN ) & # ( "groupName" ; $groupName ) & # ( "groupDomain" ; $groupDomain ) ]
            #
            Set Variable [ $result ; Value: Get ( ScriptResult ) ]
            If [ $result <> 0 ]
                Show Custom Dialog [ "Add group error" ; $result ]
                Exit Script [ Text Result: $result ]
            End If
        End If
    #
    Set Variable [ $groupIndex ; Value: $groupIndex + 1 ]
    Exit Loop If [ $groupIndex > $groupCount ]
    #
    End Loop
End If
#
# Exit with a success result
Exit Script [ Text Result: 0 ]

See also

Release notes

Blog Entries

This function is free to use.

Created 11st December 2017, last changed 27th July 2021


LDAP.Add - LDAP.AddList