Use Case: Leistungen in WILSON anlegen und synchronisieren

Mit Hilfe der WILSON API können Leistungen wie z.B. Zugfahrten aus deinem Bestandssystem nahtlos in WILSON übertragen werden, um diese für die Schicht- und Personalplanung sowie für die Zeiterfassung und Abrechnung zu nutzen. Webhooks ermöglichen zudem eine bidirektionale Kommunikation, sodass z.B. erfasste Zeiten für die Leistungen zurück in dein Bestandssystem fließen können.

Grundlegendes Konzept in WILSON

In WILSON werden einzelne Leistungen innerhalb eines "Service" gebündelt. Ein "Service" könnte zum Beispiel eine Zugfahrt von A nach D sein, die über die Zwischenhalte B und C führt. Jeder Abschnitt dieser Fahrt (A-B, B-C, C-D) stellt eine eigene "Aktivität" dar. Diese Aktivitäten können dann jeweils in einer Schicht verplant werden. Ein "Service" in WILSON besteht somit immer aus mindestens einer Aktivität. Aktivitäten benötigen zudem immer eine zeitliche und örtliche Relation.

Voraussetzungen

API-Zugangsdaten: Stelle sicher, dass du über gültige API-Zugangsdaten für die WILSON API verfügst. Mehr zur Einrichtung und Authentifizierung der API erfährst du hier.

Schritt 1: Vorbereitung der Daten im Bestandssystem

Stelle sicher, dass die Daten, die du übertragen möchtest (z.B. Zugfahrten, Transportaufträge), im richtigen Format vorliegen und die erforderlichen Informationen enthalten (z.B. Leistungs-ID, Datum, Zeit).

Schritt 2: Übertragung der Leistungen an WILSON

Sende die vorbereiteten Daten aus deinem Bestandssystem an die WILSON API. Nutze dazu den entsprechenden API-Endpunkt und füge den Bearer Token in die Autorisierungs-Header ein.

Du hast die Möglichkeit, die IDs der Objekte aus dem Bestandssystem auch in WILSON zu speichern, um diese später wieder zu identifizieren oder zu suchen - nutze dafür das Feld externalId welches sowohl für Services als auch Aktivitäten existiert.

Beim Anlegen von Aktivitäten musst du einen betrieblichen Status im Feld operationalStatus setzen - dazu gibt es folgende Optionen: not-started, ongoing, completed, skipped-by-user, paused, parked, cancelled

Ebenfalls musst du die Aktivitätskategorie auswählen. Die verfügbaren Kategorien findest du in dieser Liste oder sie können auch über die API abgefragt werden. Infos zur API findest du hier.

Beispiel:

POST /services HTTP/1.1
Host: api.wilson.com
Authorization: Bearer your_auth_token
Content-Type: application/json

{
  "name": "4711",
  "externalId": "12345",
  "startDate": "2024-05-21",
  "comment": "Your comment goes here",
  "organizationalUnitId": "333e3333-e29b-41d4-a716-8889997777",
  "activities": [
    {
      "name": "4711",
      "startDatetime": "2024-05-21T10:00:00Z",
      "endDatetime": "2024-05-21T12:00:00Z",
      "activityCategoryId": "activityCategoryID",
      "operationalStatus": "not-started",
      "externalId": "string",
      "viaLocationIds": [
        "locationID"
      ],
      "shiftId": "string",
      "startLocationId": "locationID",
      "endLocationId": "locationID",
      "agreementId": "string",
      "professionId": "string"
    }
  ]
}

Schritt 3: Aktualisierung von Leistungen in WILSON

Falls ein Nutzer in dem Bestandssystem Leistungen verändert, können diese Veränderungen entsprechend in WILSON geupdated werden. Dazu benötigst du die WILSON ID des entsprechenden Services. Diese kann entweder im Bestandssystem nach erfolgreicher Übertragung gespeichert werden oder vorab durch eine Suche über das externalId Feld identifiziert werden.

Beispiel:

PATCH /services/:id HTTP/1.1
Host: api.wilson.com
Authorization: Bearer your_auth_token
Content-Type: application/json

{
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Zugfahrt von A nach B",
    "externalId": "12345",
    "startDate": "2024-05-21",
    "comment": "Your comment goes here",
    "organizationalUnitId": "333e3333-e29b-41d4-a716-8889997777",
    "activities": []
}

Schritt 4: Integration der übertragenen Leistungen in die Schichtplanung

Nach der Übertragung kannst du die Leistungen in WILSON in Schichten verplanen. Dies erfolgt über die Benutzeroberfläche von WILSON.

Schritt 5: Zeiterfassung und Abrechnung

Die Durchführung der Schicht sowie die Zeiterfassung können nun in WILSON erfolgen. Nach Abschluss der Schicht können die erfassten Zeiten für die Lohnabrechnung (WILSON Payroll) und Leistungsabrechnung (WILSON Billing) verwendet werden.

Schritt 6: Rückübertragung erfasster Zeiten an das Bestandssystem

Nutze Webhooks in WILSON, um erfasste Zeiten und andere relevante Daten an dein Bestandssystem zurückzuschicken.