Unterschiede

Hier werden die Unterschiede zwischen zwei Versionen angezeigt.

Link zu dieser Vergleichsansicht

Beide Seiten der vorigen RevisionVorhergehende Überarbeitung
Nächste Überarbeitung
Vorhergehende Überarbeitung
de:survey:mailing-api [01.02.2018 15:54] – [Manueller Aufruf] msd-mediade:survey:mailing-api [10.12.2023 21:12] (aktuell) admin
Zeile 6: Zeile 6:
   * Optional den Versand einzelner Serienmails auslösen, ebenfalls automatisiert durch eine externe Software.   * Optional den Versand einzelner Serienmails auslösen, ebenfalls automatisiert durch eine externe Software.
   * Personalisierte Links zum Fragebogen erstellen, die genauso funktionieren wie die personalisierten Links in Serienmails.   * Personalisierte Links zum Fragebogen erstellen, die genauso funktionieren wie die personalisierten Links in Serienmails.
 +  * Abruf des Teilnahmestatus für ein Serienmail.
  
 Eine wesentliche Anwendung der API-Funktion für Serienmails ist die Anbindung eines Shop-Systems. So kann man einem Kunden etwa nach Kauf der Zugangsberechtigung einen gültigen Teilnahme-Link zum Fragebogen übermitteln. Eine wesentliche Anwendung der API-Funktion für Serienmails ist die Anbindung eines Shop-Systems. So kann man einem Kunden etwa nach Kauf der Zugangsberechtigung einen gültigen Teilnahme-Link zum Fragebogen übermitteln.
Zeile 12: Zeile 13:
 ===== Hintergrund ===== ===== Hintergrund =====
  
-Für gewöhnlich erstellt SoSci Survey eine personalisierten URL zur Teilnahme an einer Befragung in dem Moment, wenn Sie eine [[:de:survey:mailing|Serienmail versenden]]. Mittels [[:de:survey:mailing#seriennummern|Seriennummern]] lassen sich manuell personalisierte Links erstellen, allerdings mit Einschränkungen bei der Anonymität und Funktionialität -- und Seriennummern benötigen eine andere [[:de:create:access|Zugriffsbeschränkung]] im Fragebogen als Serienmails.+Für gewöhnlich erstellt SoSci Survey eine personalisierten URL zur Teilnahme an einer Befragung in dem Moment, wenn Sie eine [[:de:survey:mailing|Serienmail versenden]]. Alternativ kann man mittels [[:de:survey:serials]] manuell personalisierte Links erstellen, allerdings mit Einschränkungen bei der Anonymität und Funktionialität -- und Teilnahmecodes benötigen eine andere [[:de:create:access|Zugriffsbeschränkung]] im Fragebogen als Serienmails.
  
-Mit der Funktion **Einladungen verschicken** -> **API-Zugriff** können Sie personalisierte Links zum Fragebogen erstellen und ggf. in einer externen Software verwenden, die genauso funktionieren wie die personalisierten Links in Serienmails. Allerdings wird dabei keine E-Mail verschickt und es ist nicht einmal eine E-Mail-Adresse notwendig.+Mit der Funktion **Einladungen verschicken** -> **API-Zugriff** können Sie personalisierte Links zum Fragebogen erstellen und ggf. in einer externen Software verwenden, die genauso funktionieren wie die personalisierten Links in Serienmails. Allerdings wird dabei nicht zwangsläufig eine E-Mail verschickt. Wenn keine Serienmail verschickt werden soll, ist nicht einmal eine E-Mail-Adresse notwendig.
  
  
-===== Verwendung =====+===== Adresseinträge erstellen =====
  
-  * Legen Sie zunächst unter **Einladungen verschicken** -> **Serienmails** eine neue Serienmail an. Diese wird zwar nicht verschickt, aber hier können Sie alle Einstellungen für den Link vornehmen und den Teilnahmestatus kontrollieren.+  * Legen Sie zunächst unter **Einladungen verschicken** -> **Serienmails** eine neue Serienmail an. Diese wird nicht zwangsläufig verschickt: ob oder ob nichtkann man später festlegen. Aber hier können Sie alle Einstellungen für den Link vornehmen und den Teilnahmestatus kontrollieren.
   * Anschließend wählen Sie unter **Einladungen verschicken** -> **API-Zugriff** diese //Serienmail// aus. Legen Sie bei //Funktion// fest, ob die Serienmail von SoSci Survey verschickt werden soll oder nicht. Geben Sie, eventuell eine //Teilgruppe// für neue Adresseinträge an und bei //Anonymität neuer Adressen//, ob die Zuordnung von Personenkennung ([[:de:results:variables|SERIAL]]) und E-Mail-Adresse möglich sein soll.   * Anschließend wählen Sie unter **Einladungen verschicken** -> **API-Zugriff** diese //Serienmail// aus. Legen Sie bei //Funktion// fest, ob die Serienmail von SoSci Survey verschickt werden soll oder nicht. Geben Sie, eventuell eine //Teilgruppe// für neue Adresseinträge an und bei //Anonymität neuer Adressen//, ob die Zuordnung von Personenkennung ([[:de:results:variables|SERIAL]]) und E-Mail-Adresse möglich sein soll.
   * Mit dem Speichern-Symbol {{:button.save.png?nolink|Speichern}} erstellen Sie anschließend eine API-URL.   * Mit dem Speichern-Symbol {{:button.save.png?nolink|Speichern}} erstellen Sie anschließend eine API-URL.
  
-Beim Aufruf der API-URL erwartet SoSci Survey, dass eines der folgenden Identifikationsmerkmale für den (eventuell neuen) Adresseintrag mittels GET oder POST übermittelt wird:+Beim Aufruf der API-URL erwartet SoSci Survey, dass mindestens eines der folgenden Identifikationsmerkmale für den (eventuell neuen) Adresseintrag mittels GET oder POST übermittelt wird:
  
   * //email// E-Mail-Adresse   * //email// E-Mail-Adresse
   * //mobile// Mobil-Nummer für SMS-Versand   * //mobile// Mobil-Nummer für SMS-Versand
-  * //uid// Eindeutige Kennung für den Adressat+  * //uid// Eindeutige Kennung für den Adressat (nur ASCII-Zeichen)
  
 Wenn die API-URL ''%%https://www.soscisurvey.de/PROJEKT/?act=83w7vaYqaeakXH7axpH2Yexu%%'' lautet, könnte ein gültiger Aufruf etwa wie folgt aussehen. Dabei wird als Identifikationsmerkmal eine Kennung (''uid'', User ID) verwendet: Wenn die API-URL ''%%https://www.soscisurvey.de/PROJEKT/?act=83w7vaYqaeakXH7axpH2Yexu%%'' lautet, könnte ein gültiger Aufruf etwa wie folgt aussehen. Dabei wird als Identifikationsmerkmal eine Kennung (''uid'', User ID) verwendet:
Zeile 33: Zeile 34:
     https://www.soscisurvey.de/PROJEKT/?act=83w7vaYqaeakXH7axpH2Yexu&uid=112233aabbcc     https://www.soscisurvey.de/PROJEKT/?act=83w7vaYqaeakXH7axpH2Yexu&uid=112233aabbcc
  
-Falls ein passender Eintrag in der Adressliste gefunden wird, wird diese verwendet. Ansonsten wird unter **Einladungen verschicken** -> **Adressliste** ein neuer Eintrag erstellt.+Falls ein passender Eintrag in der Adressliste gefunden wird, wird dieser verwendet. Ansonsten wird unter **Einladungen verschicken** -> **Adressliste** ein neuer Eintrag erstellt.
  
 SoSci Survey erstellt nun einen gültigen Teilnahmelink und übermittelt diesen als Antwort auf den Aufruf als JSON zurück. SoSci Survey erstellt nun einen gültigen Teilnahmelink und übermittelt diesen als Antwort auf den Aufruf als JSON zurück.
  
  
-===== Rückgabewert =====+==== Rückgabewert ====
  
 Die Antwort auf eine gültige Anfrage könnte etwa wie folgt aussehen: Die Antwort auf eine gültige Anfrage könnte etwa wie folgt aussehen:
Zeile 62: Zeile 63:
  
  
-===== Manueller Aufruf =====+==== Manueller Aufruf ====
  
 Der **API-Zugriff** ist eigentlich für einen automatisierten Aufruf durch eine externe Software ausgelegt (Maschine-zu-Maschine Kommunikation), kann auch dafür "missbraucht" werden, manuell gültige Teilnahme-Links zu erstellen. Der **API-Zugriff** ist eigentlich für einen automatisierten Aufruf durch eine externe Software ausgelegt (Maschine-zu-Maschine Kommunikation), kann auch dafür "missbraucht" werden, manuell gültige Teilnahme-Links zu erstellen.
Zeile 76: Zeile 77:
 Ihr Browser zeigt nach jedem Aufruf eine gültige Teilnahme-URL an, die etwa per E-Mail an die Teilnehmer verschickt werden kann. Ihr Browser zeigt nach jedem Aufruf eine gültige Teilnahme-URL an, die etwa per E-Mail an die Teilnehmer verschickt werden kann.
  
-Eine Funktion zum automatisierten Erstellen einer größeren Anzahl von Teilnahmelinks ohne externe Software ist in Planung, derzeit allerdings nur mit geringer Priorität. Falls die Anonymität nicht kritisch ist (oder wenn sie ganz besonders kritisch ist), kann dafür die [[:de:survey:mailing#seriennummern|Seriennummern-Funktion]] zum Einsatz kommen.+Eine Funktion zum automatisierten Erstellen einer größeren Anzahl von Teilnahmelinks ohne externe Software ist in Planung, derzeit allerdings nur mit geringer Priorität. Falls die Anonymität nicht kritisch ist (oder wenn sie ganz besonders kritisch ist), kann dafür die Funktion [[:de:survey:serials]] zum Einsatz kommen. 
 + 
 + 
 +===== Teilnahmestatus Teilnahmecode ===== 
 + 
 +  * Wählen Sie unter **Einladungen verschicken** -> **API-Zugriff** bei //Funktion//, dass Sie den Status eines Teilnahmecodes abfragen möchten. 
 +  * Mit dem Speichern-Symbol {{:button.save.png?nolink|Speichern}} erstellen Sie anschließend eine API-URL. 
 + 
 +Beim Aufruf der API-URL erwartet SoSci Survey, dass ein Parameter //serial// mit dem zu prüfenden Teilnahmecode übermittelt wird. 
 + 
 +Wenn die API-URL ''%%https://www.soscisurvey.de/PROJEKT/?act=exu83w7vaYqaeakXH7axpH2Y%%'' lautet, könnte ein gültiger Aufruf zur Überprüfung des Teilnahmecodes "CD246802" etwa wie folgt aussehen. 
 + 
 +    https://www.soscisurvey.de/PROJEKT/?act=exu83w7vaYqaeakXH7axpH2Y&serial=CD246802 
 + 
 +Als Rückgabewert wird ein JSON-String mit folgender Struktur geliefert: 
 + 
 +<code javascript> 
 +
 +  result:    "ok", 
 +  code:      "CD246802", 
 +  started:   true, 
 +  completed: false, 
 +  notice:    "", 
 +  error:     null 
 +
 +</code> 
 + 
 +Die Attribute haben die folgende Bedeutung: 
 + 
 +  * ''result'' -- Rückgabewert der Anfrage, kann die Wert "ok" oder "error" annehmen 
 +  * ''code'' -- Der abgefragte Teilnahmecode 
 +  * ''started'' -- Wurde der Teilnahmecode verwendet, um einen Fragebogen zu starten (boolean) 
 +  * ''completed'' -- Wurde der begonnene Fragebogen bis zur letzten Seite ausgefüllt (boolean) 
 +  * ''notice'' -- Eine eventuell für den Teilnahmecode gespeicherter Notiz 
 +  * ''error'' -- Fehlermeldung, falls ''result'' den Wert "error" hat 
 +    * "not found" -- Der gesuchte Teilnahmecode ist im Befragungsprojekt nicht bekannt 
 + 
 +Im Fehlerfall wird nur der Status-Code und eine Fehlermeldung zurückgegeben, falls vorhanden auch den angefragten Teilnahmecode: 
 + 
 +<code javascript> 
 +
 +  result:    "error", 
 +  error:     "not found", 
 +  code:      "CD246802" 
 +
 +</code> 
 + 
 + 
 +===== Teilnahmestatus für Adresseintrag ===== 
 + 
 +  * Wählen Sie unter **Einladungen verschicken** -> **API-Zugriff** bei //Funktion//, dass Sie den Status eines Adresseintrags abfragen möchten. 
 +  * Mit dem Speichern-Symbol {{:button.save.png?nolink|Speichern}} erstellen Sie anschließend eine API-URL. 
 + 
 +Beim Aufruf der API-URL erwartet SoSci Survey, dass mindestens ein Parameter angegeben wird, um den Adresseintrag zu identifizieren. Falls mehrere Eigenschaften angegeben werden, wird nach einem Adresseintrag gesucht, der alle Eigenschaften hat. Der Adresseintrag kann anhand folgender Eigenschaften gesucht werden: 
 + 
 +  * ''serial'' -> Personencode des Adresseintrags 
 +  * ''email'' -> E-Mail-Adresse 
 +  * ''mobile'' -> Mobilnummer 
 +  * ''uid'' -> Eindeutige Kennung für den Adresseintrag 
 + 
 +Wenn die API-URL ''%%https://www.soscisurvey.de/PROJEKT/?act=erSoqORu4OPzGeWyetpwmbMu%%'' lautet, könnte ein gültiger Aufruf zur Überprüfung des Teilnahmestatus von "person@example.com" etwa wie folgt aussehen. 
 + 
 +    https://www.soscisurvey.de/PROJEKT/?act=exu83w7vaYqaeakXH7axpH2Y&email=person@example.com 
 + 
 +Als Rückgabewert wird ein JSON-String mit folgender Struktur geliefert: 
 + 
 +<code javascript> 
 +
 +  result:  "ok", 
 +  serial:  null 
 +  email:   "person@example.com" 
 +  mobile:  null 
 +  uid:     null 
 +  mailings: { 
 +    M1: { 
 +      id:         1 
 +      status:     "sent" 
 +      statusMail: "delivered" 
 +      statusSMS:  "none" 
 +      sendTime:   "2023-11-09" 
 +    }, 
 +    M2: { 
 +      id:         2 
 +      status:     "skipped", 
 +      statusMail: "none", 
 +      statusSMS:  "none", 
 +      sendTime:   "2023-07-02" 
 +    } 
 +  }, 
 +  error:   null 
 +
 +</code> 
 + 
 +Im ersten Teil der Antwort werden die verwendeten Suchparameter zurückgegeben. 
 + 
 +Der Teilnahmestatus wird für jede Serienmail angegeben, für welche ein Versand an diesen Adresseintrag versucht wurde. Als Schlüssel für die ''mailings'' wird dabei "M" und die ID der Serienmail verwendet. 
 + 
 +Die Attribute haben die folgende Bedeutung: 
 + 
 +Im Fehlerfall wird nur der Status-Code und eine Fehlermeldung zurückgegeben, falls vorhanden auch den angefragten Teilnahmecode: 
 + 
 +<code javascript> 
 +
 +  result:    "error", 
 +  error:     "not found", 
 +  serial:    null 
 +  email:     "nobody@example.com" 
 +  mobile:    null 
 +  uid:       null 
 +
 +</code> 
de/survey/mailing-api.1517496848.txt.gz · Zuletzt geändert: 01.02.2018 15:54 von msd-media
 
Falls nicht anders bezeichnet, ist der Inhalt dieses Wikis unter der folgenden Lizenz veröffentlicht: CC Attribution-Share Alike 4.0 International
Driven by DokuWiki