Zum Inhalt

Migrationsleitfaden

2.0.x zu 2.0.18

Der nachfolgende Migrationsleitfaden ist lediglich für ATLAS-API Nutzer relevant, welche Datenbank-Übertragungskanäle per API verwalten. Sollten Sie keine Datenbank-Übertragungskanäle per API verwalten, müssen keine Anpassungen vorgenommen werden.

Wichtig: Die Änderungen treten sofort mit dem Release in Kraft. Alte Endpunkte und Objektbestandteile sind nicht mehr verfügbar.

Objekte

Am Objekt IntegrationDatabase sind folgende Änderungen nötig:

  • databaseLocation ist nun location
  • databasePort ist nun port
  • databaseUser ist nun user
  • databasePassword ist nun password
  • databaseName ist nun dbName
  • databaseType ist nun type und version
  • databaseTable fällt auf dieser Ebene weg, ebenso wie deviceIds
  • Dafür gibt es nun deviceIdsByTableName (solange der Parameter attachTables gesetzt ist). Dieses Objekt beinhaltet ein Array mit den Feldern deviceIds und tableName.
    • Durch das Entfallen des Feldes deviceIds ist es nun auch nicht mehr möglich, eine Liste an Sensor-IDs beim Erstellen oder Aktualisieren einer Integration zu übermitteln.
    • Stattdessen sind nun zwei Endpunkte POST/DELETE /integration/database/{integrationId}/devices/{deviceId} für das Hinzufügen bzw. Entfernen von Sensoren zu verwenden.

Änderung der Endpunkte

Der Grundpfad wurde von /dbhook zu /integration/database geändert. Der Endpunkt zum Verbindungstest mit einer Datenbank ist nicht mehr unter /test, sondern unter /test-connection erreichbar.

2.0.x zu 2.0.17

Der nachfolgende Migrationsleitfaden ist lediglich für ATLAS-API Nutzer relevant. Sollten Sie keine Accounts, Rechnungsaccounts oder Benutzer und deren Module/Berechtigungen per API verwalten, müssen Sie keine Anpassungen vornehmen.

Wichtig:
Alle Endpunkte und Objekte sind aktuell noch in ihrer ursprünglichen Form vorhanden. Sie werden allerdings in zukünftigen Versionen nach und nach vollständig entfernt. Sie können die neuen Endpunkte ab sofort nutzen und Ihre Schnittstellen entsprechend anpassen. Wir empfehlen Ihnen die Anpassungen zeitnah einzuplanen. Wir informieren Sie entsprechend, sobald die geänderten Endpunkte und Objekte vollständig entfernt werden.

Allgemeine Änderungen

Die Angabe von Adressen in ATLAS ist nun komplett standardisiert. Sie besteht immer aus folgenden Feldern: street, houseNumber, postalCode, state, city, country
All diese Felder sind verpflichtend und müssen angegeben werden. Die Angabe einer Adresse kann aber sowohl optional, als auch verpflichtend sein. Das bestimmt der jeweilige Anwendungsfall.

Account-Verwaltung

Objekte

Das Objekt Company bleibt bestehen und kann vorläufig ohne Änderungen genutzt werden. In Zukunft sind aber einige Änderungen an dem Objekt nötig:

  • deletedAt ist nun disabledAt
  • entityType ist nun legalForm
  • phone ist nun phoneNumber
  • fax ist nun faxNumber
  • modules ist nun moduleIds, wobei sich hier auch der Inhalt verändern muss. Vorher wurde eine Liste an Module-Objekten übergeben, jetzt ist es nur noch eine Liste aus den IDs der Module.
  • childCount, userCount und billingAccountCount sind nun in einem extra Unterobjekt im Feld statistics zu finden. Das Feld childCount heißt dort nun childCompaniesCount.

Beim Anlegen oder Aktualisieren von Company-Objekten werden diese nun genauer validiert:

  • Pflichtfelder sind parentId, name, email. Wenn ein Pflichtfeld nicht angegeben ist, wird die Anfrage mit dem HTTP-Statuscode 400 abgebrochen.
  • Die Adressfelder visitAddress und postalAddress sind leer zu lassen, wenn keine Adresse angegeben werden soll. Sind sie befüllt, muss ein valides Address-Objekt übermittelt werden.
  • Beim Anlegen/Aktualisieren eines Accounts müssen auch immer dessen Module als Liste von IDs im Objekt enthalten sein. Übergangsweise können auch noch die kompletten Module-Objekte in einer Liste übermittelt werden.
  • Bisher wurde ein entferntes Modul nicht von allen Benutzern des Accounts, Mandanten des Accounts und auch nicht von den Benutzern der Mandanten entfernt.
    • Beim Bearbeiten eines Accounts über den neuen Endpunkt PUT /companies/{companyId} wird in all diesen Fällen ein HTTP-Statuscode 400 zurückgegeben und das Modul muss überall manuell entfernt werden. Mit dem Parameter unlinkModulesFromChildCompanies wird dieser Vorgang automatisiert durchgeführt.
    • Vorsicht: Beim Bearbeiten eines Accounts über den alten Endpunkt PUT /company/{companyId} wird nun, um evtl. auftretende Fehler zu vermeiden, dieser Vorgang auch automatisch ausgeführt!

Änderung der Endpunkte

Für die Account-Verwaltung wurde der Grundpfad von /company zu /companies geändert. Um aber die gleiche Ausgabe wie vorher zu erhalten, sind nun teilweise zusätzliche Parameter nötig:

  • GET /company ist nun GET /companies mit den Parametern ?includeChildCompanies=false&attachModuleIds=true&attachStatistics=true.
  • GET /company/{companyId} ist nun GET /companies/{companyId} mit den Parametern ?attachModuleIds=true&attachStatistics=true.
  • GET /company/my ist nun GET /companies mit den Parametern ?includeRequestCompany=false&attachModuleIds=true&attachStatistics=true.
  • GET /company/all ist nun GET /companies mit den Parametern ?attachModuleIds=true&attachStatistics=true. Der Parameter inactive heißt nun includeDisabled.
  • PUT /company/{companyId}/activate ist nun PUT /companies/{companyId}/reactivate und enthält nun auch direkt den reaktivierten Account.
  • GET /company/{companyId}/modules ist nun GET /companies/{companyId}/modules weiterhin mit dem optionalen Parameter includePermissions.
  • GET /company/{companyId}/modules/all ist nun GET /companies/{companyId}/modules/all neu mit dem optionalen Parameter includePermissions.
  • DELETE /company/{companyId}/external-links/{externalLinkId} ist nun DELETE /companies/{companyId}/external-links/{externalLinkId} mit dem HTTP-Statuscode 204, statt bisher 200.

Neue Endpunkte

Neben diesen Änderungen gibt es auch neue Endpunkte, die weitere Informationen direkt bereitstellen:

  • Über den Endpunkt GET /companies/own kann nun der eigene Account von der API direkt abgerufen werden.
  • Der Endpunkt GET /companies/{companyId}/modules/available liefert alle noch nicht verwendeten Module für den Account.
  • Mit POST /companies/{companyId}/modules/{moduleId} lässt sich einem Account ein Modul hinzufügen, ohne dafür den kompletten Account bearbeiten zu müssen.
  • Zum Entfernen eines Modules kann auch der Endpunkt DELETE /companies/{companyId}/modules/{moduleId} verwendet werden. Auch hier gibt es den Parameter unlinkModuleFromChildCompanies zum direkten Entfernen des Moduls bei allen Benutzern des Accounts/Mandanten und bei den Mandanten selbst.

Die standardmäßige Kartenposition eines Accounts wird nun mit eigenen Endpunkten und eigenem Objekt abgebildet. Daher entfallen folgende Endpunkte dauerhaft und werden durch neue ersetzt:

  • Der Endpunkt GET /heatmap/position des Heatmap-Controllers ist durch den Endpunkt GET /companies/{companyId}/settings/map/default-position ersetzt.
  • Auch der Endpunkt PUT /company/{companyId}/map zum Anlegen/Aktualisieren dieser Position wurde entfernt und durch den Endpunkt PUT /companies/{companyId}/settings/map/default-position ersetzt.
  • Durch das Auslagern der standardmäßigen Kartenposition in die neu entstandenen Account-Einstellungen wurden auch die drei Felder mapLatitude, mapLongitude, mapZoom aus dem Objekt Company entfernt.

Rechnungsaccount-Verwaltung

Objekte

Das Objekt BillingAccount bleibt bestehen und kann vorläufig ohne Änderungen genutzt werden. In Zukunft sind aber einige Änderungen an dem Objekt nötig:

  • Die Felder status, number und deliveryMethod sind schon jetzt ersatzlos entfallen
  • deletedAt ist nun disabled_at
  • contractual_organization ist nun name
  • salutation ist nun contact_person_salutation
  • contact ist nun contact_person
  • email ist nun contact_email
  • iban ist nun payment_iban
  • bic ist nun payment_bic
  • street, houseNumber, postalCode, state, city, country sind nun im Feld address zusammengefasst.

Beim Anlegen oder Aktualisieren von Billing-Account-Objekten werden diese nun genauer validiert:

  • Pflichtfelder sind: name, contactPersonSalutation, contactPerson, contactEmail, address. Wenn ein Pflichtfeld nicht angegeben ist, wird die Anfrage mit dem HTTP-Statuscode 400 abgebrochen.
  • Das Feld address muss ein gültiges Address-Objekt enthalten. Vorübergehend können noch die einzelnen Felder dafür verwendet werden.

Änderung der Endpunkte

Für die Verwaltung der Rechnungsaccounts wurde der Grundpfad von /billing-account zu /billing-accounts geändert. Um aber die gleiche Ausgabe wie vorher zu erhalten, sind nun teilweise zusätzliche Parameter nötig:

  • GET /billing-account ist nun GET /billing-accounts. Der Parameter showInactive heißt nun includeDisabled.
  • DELETE /billing-account/{billingAccountId} ist nun DELETE /billing-accounts/{billingAccountId}, allerdings mit dem HTTP-Status 204 statt 200
  • PUT /billing-account/{billingAccountId}/activate ist nun PUT /billing-accounts/{billingAccountId}/reactivate und gibt nun auch direkt den reaktivierten Rechnungsaccount zurück.

Durch das Entfernen des Feldes status aus dem Objekt BillingAccount ist auch der Endpunkt GET /billing-account/status entfallen.

Neue Endpunkte

  • Der Endpunkt GET /billing-accounts ist um den Parameter includeFromChildCompanies (Standardwert true) erweitert worden. Mit diesem Parameter lässt sich einstellen, ob auch Rechnungsaccounts der Mandanten mit ausgegeben werden sollen.
  • Zusätzlich gibt es noch den neuen Endpunkt GET /billing-accounts/{billingAccountId} um einen speziellen Rechnungsaccount abzurufen. Der optionale Parameter includeDisabled erlaubt es auch hier, deaktivierte Rechnungsaccounts abzurufen.

Benutzer-Verwaltung

Objekte

Das Objekt User bleibt bestehen und kann vorläufig ohne Änderungen genutzt werden. In Zukunft sind aber einige Änderungen an dem Objekt nötig:

  • Die Felder defaultBillingAccountId, mobile, emailOptOut, phoneOptOut und mobileOptOut sind ersatzlos entfallen.
  • role ist nun position.
  • phone ist nun phone_number.
  • modules ist nun moduleIds, wobei sich hier auch der Inhalt verändern muss. Vorher wurde eine Liste an Module-Objekten übergeben, jetzt ist es nur noch eine Liste aus den IDs der Module.
  • permissions ist nun permissionIds, wobei sich hier auch der Inhalt verändern muss. Vorher wurde eine Map aus Permission-Objekten übergeben, jetzt ist es nur noch eine Liste aus den IDs der Berechtigungen.

Auch das Objekt PasswordContainer, welches ab sofort UserPasswordContainer heißt, wird in Zukunft ein geändertes Feld haben:

  • confirmPassword ist nun confirmationNewPassword.

Für alle Endpunkte, die auf /own enden, sind keine besonderen Rechte erforderlich. Alle anderen Endpunkte benötigen mindestens das Administrationsmodul für Benutzer.
Beim Anlegen oder Aktualisieren von User-Objekten werden diese nun genauer validiert:

  • Pflichtfelder sind email, salutation, firstname, lastname. Wird ein Pflichtfeld nicht angegeben, wird die Anfrage mit dem HTTP-Statuscode 400 abgebrochen.
  • Beim Anlegen ist zusätzlich noch das Feld password verpflichtend. Eine Passwortänderung findet über separate Endpunkte statt.
  • Ist das Feld address angegeben, muss es ein gültiges Address-Objekt enthalten.
  • Das Feld email muss für aktive und deaktivierte Benutzer einmalig sein.
    • Über den Endpunkt GET /users/email-in-use lässt sich prüfen, ob eine E-Mail bereits verwendet wird.
    • Wird beim Anlegen oder Bearbeiten eine bereits verwendete E-Mail angegeben, wird der Vorgang mit dem HTTP-Statuscode 409 abgebrochen.
    • Beim Bearbeiten gilt zu beachten, dass die E-Mail des eigenen Benutzers NICHT änderbar ist!
    • Die E-Mail eines permanent gelöschten Benutzers kann für einen anderen Benutzer aber wiederverwendet werden.
  • Über das optionale Feld expireAt kann angegeben werden, ab welchem Tag sich ein Benutzer nicht mehr anmelden kann. Damit ist der Benutzer NICHT automatisch deaktiviert, lediglich ein Login ist nicht mehr möglich.
  • Zum Aktualisieren des eigenen Benutzers kann auch der Endpunkt PUT /users/own genutzt werden.

Änderung der Endpunkte

Für die Verwaltung der Benutzer wurde der Grundpfad von /user zu /users geändert. Um aber die gleiche Ausgabe wie vorher zu erhalten, sind nun teilweise zusätzliche Parameter nötig:

  • GET /user/company/{companyId} ist nun GET /users mit den Parametern ?includeFromChildCompanies=false&attachModuleIds=true&attachPermissionIds=true. Der Parameter inactiv e heißt nun includeDisabled.
  • GET /user/all ist nun GET /users mit den Parametern ?attachModuleIds=true&attachPermissionIds=true. Der Parameter showInactive heißt nun includeDisabled.
  • GET /user/account ist nun GET /users/own mit den Parametern ?attachModuleIds=true&attachPermissionIds=true.
  • DELETE /user/{userId} ist nun DELETE /users/{userId} mit dem HTTP-Statuscode 204, statt bisher 200.
  • DELETE /user/{userId}/disable ist nun DELETE /users/{userId}/deactivate.
  • PUT /user/{userId}/activate ist nun PUT /users/{userId}/reactivate und enthält nun auch direkt den reaktivierten Benutzer.
  • POST /user/{userId}/change-user-password ist nun PUT /users/{userId}/password. Als HTTP-Body ist im neuen Endpunkt nicht mehr nur ein Passwort als String anzugeben, sondern ein vollständiges UserPasswordContainer-Objekt.
  • PUT /user/change-own-password ist nun PUT /users/own/password.
  • POST /user/{userId}/module/{moduleId} ist nun POST /users/{userId}/modules/{moduleId}.
  • DELETE /user/{userId}/module/{moduleId} ist nun DELETE /users/{userId}modules/{moduleId} mit dem HTTP-Statuscode 204, statt bisher 200.
  • POST /user/{userId}/permission/{permissionId} ist nun POST /users/{userId}/permissions/{permissionId}.
  • DELETE /user/{userId}/permission/{permissionId} ist nun DELETE /users/{userId}/permissions/{permissionId} mit dem HTTP-Statuscode 204, statt bisher 200.
  • PUT /user/password/reset-by-email ist nun PUT /users/password/reset. Im neuen Endpunkt ist nun kein HTTP-Body mehr nötig, dafür aber der Parameter email. Der optionale Parameter forceSendNew heißt nun forceResendConfirmationEmail.
  • GET /user/password/reset-by-email/{resetToken}/validate ist nun GET /users/password/reset/{resetToken}/validate.
  • PUT /user/password/reset-by-email/{resetToken} ist nun PUT /users/password/reset/{resetToken}. Als HTTP-Body wird im neuen Endpunkt kein eigener Passwort-Container mehr benötigt, sondern das UserPasswordContainer-Objekt verwendet.

Ein Benutzer kann nur deaktiviert (DELETE /users/{userId}/deactivate) oder permanent gelöscht werden (DELETE /users/{userId}). Der Unterschied besteht darin, dass ein deaktivierter Benutzer auch wieder aktiviert (PUT /users/{userId}/reactivate) werden kann. Ein permanent gelöschter Benutzer kann aber nicht wieder aktiviert werden. Daher ist es nötig, einen Benutzer zuerst zu deaktivieren und erst im Anschluss kann dieser permanent gelöscht werden.

Module und Berechtigungen

Für die Module und Berechtigungen eines Benutzers gibt es weiterhin folgendes zu beachten:

  • Module und Berechtigungen werden weiterhin einzeln hinzugefügt oder entfernt.
  • Beim Hinzufügen eines Moduls, auf das der Account des Benutzers keinen Zugriff hat, wird der HTTP-Statuscode 412 zurückgeliefert.
  • Ist das Modul diesem Benutzer bereits hinzugefügt, wird der HTTP-Statuscode 409 zurückgeliefert.
  • Beim Entfernen eines Moduls von einem Benutzer werden nun auch automatisch alle Berechtigungen dieses Moduls entfernt.
  • Auch beim Hinzufügen von Berechtigungen, für die dem Benutzer das passende Modul fehlt, wird der HTTP-Statuscode 412 zurückgeliefert.
  • Wenn die Berechtigung für den Benutzer schon vorhanden ist, wird auch der HTTP-Statuscode 409 zurückgeliefert.
  • Zusätzlich zum Anhängen der Modul- oder Berechtigungs-IDs an das User-Objekt, können nun auch direkt alle dem Benutzer zugewiesenen Module (GET /users/{userId}/modules) oder Berechtigungen (GET /users/{userId}/permissions) abgefragt werden.

Passwort ändern

Das Ändern eines Passworts ist entweder als Administrator oder nur für den eigenen Benutzer möglich:

  • Jeder Benutzer hat die Möglichkeit, sein eigenes Passwort über den Endpunkt PUT /users/own/password zu ändern. Dabei muss das Objekt UserPasswordContainer als HTTP-Body übermittelt werden und neben dem neuen Passwort inkl. seiner Bestätigung auch das alte Passwort enthalten.
  • Als Administrator mit dem Recht Passwörter für Benutzer zu ändern, muss der Endpunkt PUT /users/{userId}/password verwendet werden. Auch dort wird das Objekt UserPasswordContainer im HTTP-Body benötigt. Es genügen hier allerdings das neue Passwort und seine Bestätigung.