Push sync REST API

In Embrace is een REST API beschikbaar dat gebruikt kan worden om gebruikers in Embrace aan te maken of bij te werken. Deze API wordt gebruikt door het PowerShell script voor synchronisatie met Active Directory en Entra ID.

Maar deze REST endpoint kan ook door andere syncs gebruikt worden. Dit document geeft een beknopte beschrijving van de werking.

Dit artikel bevat de volgende secties:

• Werking
• Avatars / profielfoto's

Werking

De volgende stappen moeten doorlopen worden:

• Genereer een XML met daarin alle users
• Stuur deze XML middels een POST naar de REST endpoint

XML formaat

<?xml version="1.0"?>
<Objects SourceName="Active Directory" SourceHost="Computername">
  <Object>
    <Property Name="EmailAddress">[e-mail]</Property>
    <Property Name="GivenName">Jan</Property>
    <Property Name="Surname">de Vries</Property>
    <Property Name="userprincipalname">[e-mail]</Property>
    <Property Name="enabled">True</Property>
    <Property Name="externalid">S-1-5-21-2516293930-792395344-1351149814-1605</Property>
    <Property Name="correlationid">S-1-5-21-2516293930-792395344-1351149814-1605</Property>
    <Property Name="samaccountname">DEV\jan</Property>
    <Property Name="DisplayName">Jan de Vries displayname</Property>
    <Property Name="middlename">middlename</Property>
    <Property Name="title">Job title</Property>
    <Property Name="description">Description</Property>
    <Property Name="organization">Organization</Property>
    <Property Name="telephonenumber">050-telephone</Property>
    <Property Name="mobilephone">06-mobile</Property>
    <Property Name="homephone">0596-home</Property>
    <Property Name="department">Department</Property>
    <Property Name="manager">[e-mail]</Property>
    <Property Name="streetAddress">street 1</Property>
    <Property Name="postalCode">Zip</Property>
    <Property Name="city">City</Property>
    <Property Name="country">NL</Property>
    <Property Name="kamernummer">Office</Property>
    <Property Name="language">NL</Property>
    <Property Name="Custom">
      <Property Name="hobbies">jan</Property>
      <Property Name="multilabel">City</Property>
    </Property>
    <Property Name="Teams">
      <Property>EmbraceSBS</Property>
      <Property>Malengo</Property>
    </Property>
    <Property Name="RemoveTeams">
      <Property>Testteam1</Property>
      <Property>Testteam2</Property>
    </Property>
  </Object>
  <Object>
   <!-- etc -->
  </Object>
</Objects>

• SourceName en SourceHost zijn optioneel maar kunnen met iedere waarde ingevuld worden en komen terug in de logfiles t.b.v. support.

Versturen via POST

Zoals bij alle REST API's van Embrace moet er een api key en een impersonation header meegestuurd worden.

De XML moet met een POST verstuurd worden naar:

/api/v1/Sync/Users?sendEmail=true&emailText=je bent uitgenodigd voor deze omgeving!&teamMembershipOnlyForNewUsers=true&archiveNonExisting=false&statusEmail=[e-mail];[e-mail]

Hierin zijn de volgende parameters mogelijk:

Veld	Omschrijving
sendEmail	True: nieuwe gebruikers krijgen een email False: nieuwe gebruiker krijgen geen email.
emailText	De tekst die in de email wordt geplaatst. Als deze leeg is dan wordt de Embrace default tekst gebruikt.
teamMembershipOnlyForNewUsers	Dit is van belang als er team lidmaatschappen in de XML zijn opgenomen. True: alleen nieuwe gebruikers worden lid gemaakt van deze teams. False: iedereen wordt iedere keer weer lid gemaakt van de opgegeven teams. Als iemand tussentijds uit een team stapt dan wordt hij bij de volgende sync weer lid gemaakt.
archiveNonExisting	True: iedereen die niet in de XML staat maar wel aanwezig is in Embrace wordt in Embrace gearchiveerd. False: personen worden alleen gearchiveerd als dit in de XML vermeld staat.
statusEmail	(optioneel) Vanaf Embrace 1.38 kan er een email gestuurd worden naar dit adres met het resultaat van de import. Meerdere e-mail adressen kunnen gescheiden worden met ;

In de XML staan ook Teams collectie en RemoveTeams collectie. Deze kunnen gebruikt worden om personen lid te maken van een team of uit een team te verwijderen. Hier mogen ook teams in staan waar een gebruiker reeds lid van is of reeds niet meer lid van is.

NOTE: RemoveTeams wordt vanaf Embrace 1.29 ondersteund.

Avatars / profielfoto's

Met de XML import kunnen geen avatars (profielfoto's) geïmporteerd worden. Hiervoor is een andere API beschikbaar, zie: ­Push sync REST API - Avatars / profielfoto's, te vinden in deze sectie van de kennisbank.