CO Rest Api

    Um den Zugriff auf die CO Rest Api zu testen bzw. um Befehle dort auszuführen kann das Tool Postman (www.postman.com) verwendet werden.

    Es gibt hierzu auch eine Anwendung (.exe) welche lokal installiert werden kann. Die Verwendung des Tools ist kostenfrei.
     

    CO Rest Api Beschreibung

    Die automatisch generierte Api Beschreibung kann über folgenden (internen) Link eingesehen werden:
    192.168.10.241:10001/Office/CoServiceRestApi/help

    Erste Schritte mit Postman

    Es muss eine neue Collection angelegt werden. Anschließend müssen im Reiter "Body" die folgenden Schritte durchgeführt werden:
    1. Auswahl von "POST"
    2. Hinterlegung der WebService URL: "https://******/Office/CoServiceRestApi/office/currentUser/authentication"
    3. Hinterlegung der folgenden Werte, als "raw":
      {
                    "Password":"xxxxxx",
                    "UserName":"xxxxxx"
      }
      Der Login muss ein echter Concept Flex Zugang mit entsprechenden Rechten sein.
    4. Den Button Send anklicken
    5. Im unteren Bereich (Body) müssen nun verschiedene Werte angezeigt werden.


    Speicherung der Zugangsdaten als Token

    Die Inhalte im Bereich Token (Mandant, Login und Key) müssen für zukünftige Aufrufe / Befehle im Header gespeichert werden.
    Hierzu wechselt man zunächst in den Tab "Headers"  und erstellt einen neuen Key "Authorization" mit den Token-Werten:


    Wie lange das Anmeldetoken gültig ist, kann über die Konfiguration 546 gesteuert werden. 
    Diese Einstellung sollte nicht zu lange gewählt werden (Sicherheitsproblem).

    Empfangen von Daten (GET)

    Sobald der Header hinterlegt wurde, kann man im Reiter Body mit dem GET Befehl Daten empfangen:
    Hierzu muss die URL wie folgt geändert werden:
    https://******/Office/CoServiceRestApi/office/aktivitaeten/830158

    Der vordere Teil ist bei jedem Aufruf identisch - https://******/Office/CoServiceRestApi/office/
    Hiernach kommt der entityName - dabei handelt es sich um die Datenbanktabelle.
    Der letzte Teil der URL ist die Laufende Nummer der Aktivität (der primäre Schlüssel).

    Im Raw-Bereich müssen keine eingaben hinterlegt werden.

    Das Ergebnis des GET-Befehls sieht wie folgt aus:


    Ermitteln von Daten OHNE primären Schlüssel (GET - Query)

    Falls man den primären Schlüssel einer Tabelle nicht kennt (z. B. die Mitarbeiternummer), kann man mit folgenden Befehl danach suchen:
    "%20" entspricht einem Leerzeichen.

     

    Post - Erstellen von neuen Datensätzen 

    Möchte man einen neuen Datensatz erstellen, z. B. eine neue Aktivität, muss man den "Post" Befehl verwenden und die laufende Nummer aus der URL entfernen:


    Nun kopiert man in den unteren Bereich des Body die Daten aus dem zuvor durchgeführten Get Befehl und entfernt alle nicht relevanten Daten.
    Möchte man eine neue Aktivität anlegen, MUSS der Eintrag des primären Schlüssels (lfdnr) vollständig gelöscht werden.

    Folgende Aktivität soll angelegt werden:
    • Firmenzuordnung "70000"
    • Von: 02.10.2023 - 09:00 Uhr
    • Bis: 02.10.2023 - 10:00 Uhr
    • Aktivitätenart: Termin (Kennung der Aktivitätenart bei uns "Besprechung"
    • Bezeichnung: Test-Aktivität über API
    • Mitarbeiter: SW29 + LP

    Post - Der Befehl (Aktivitätenanlage)

    {
       "mandant": 1,
       "aktivitaetenart": "Besprechung",
       "bezeichnung": "Test-Aktivität über API",
       "kontaktnummer": 70000,
       "datum": "2023-10-02T09:00:00+02:00",
       "enddatumzeit": "2023-10-02T10:00:00+02:00",
       "isttermin": true,  
    }

    Beim Ausführen des Befehls erscheint nun die Meldung:
    "Es muss mindestens ein Mitarbeiter oder ein Bereich zugeordnet werden."

    Das liegt daran, dass im Get-Befehl nicht die Mitarbeiter-Verknüpfung hinterlegt wird.
    Diese Verknüpfung muss ebenso im Post Befehl aufgenommen werden, hierzu muss nach dem Eintrag "isttermin" einfach noch die verknüpfte Tabelle "Aktivitätenmitarbeiter" wie folgt hinterlegt werden:
    "aktivitaetenmitarbeiter": [
    {
    "mitarbeiternummer": 31
    },
    {
    "mitarbeiternummer": 20
    }
    ]

    Der komplette Befehl sieht nun wie folgt aus:


    Führe ich diesen Befehl aus, wird mir der vollständige Code angezeigt, inkl. der neu erstellten laufenden Nummer.

    Das Ergebnis in Concept Office



    Profilfelder

    Möchte man neben den "Standard" Feldern ebenfalls Profilfelder erstellen, muss dies via PUT erfolgen.
    Es muss zuerst die Aktivität via Post (siehe oben) erstellt werden, anschließend muss die lfdnr ermittelt werden und wie folgt darauf zugegriffen werden:
    Die Felder sind wie folgt zu befüllen:
    {
       "mandant": 1,
       "auftragsnummer": 4195068,
       "profile": [
           {
               "ProfilKey": "Dienstleistung",
               "AnzeigeName": "Dienstleistung",
               "Eintraege": [
                   {
                       "ProfilName": "Dienstleistung",
                       "LfdNr": 1028,
                       "FeldName": "fap_recherche_ma",
                       "Wert": "1"
                   },
                   {
                       "ProfilName": "Dienstleistung",
                       "LfdNr": 1029,
                       "FeldName": "fap_letzte_aktualisierung",
                       "Wert": "2"
                   },
                   {
                       "ProfilName": "Dienstleistung",
                       "LfdNr": 1030,
                       "FeldName": "fap_ticket_status",
                       "Wert": "3"
                   },
                   {
                       "ProfilName": "Dienstleistung",
                       "LfdNr": 1039,
                       "FeldName": "fap_terminierung",
                       "Wert": "4"
                   },
                   {
                       "ProfilName": "Dienstleistung",
                       "LfdNr": 1031,
                       "FeldName": "fap_ticket_link",
                       "Wert": "5",
                   }
               ]
           }
       ]
    }

    Praxisbeispiel: Befüllung der Daten via make.com 

    Wir nutzen die Concept Office API beispielsweise zur Erfassung von Zammad-Ticketaktivitäten.
    Zammad löst einen Webhook mit allen Ticketinhalten (z. B.: CO Firmennummer, Gearbeitete Zeit, Mitarbeiter, etc.) aus.
    Das Tool make.com kann auf die einzelnen Bestandteile des Webhooks zugreifen und die Inhalte können anschließend in den Api Befehl übernommen werden.
    Dadurch erhalten wir in Concept Office Office ALLE Ticketaktivitäten inkl. Zeiten und können somit sicherstellen, dass keine Abrechenbare Zeit verloren geht.



    Veröffentlicht