Collaboration-API Dokumentation
Die Collaboration-API in FirstSpirit erweitert die integrierte Kommentarfunktion der Plattform, die den Benutzern bereits über den ContentCreator zur Verfügung steht. Während Redakteure Kommentare direkt in der Benutzeroberfläche erstellen und verwalten können, bietet die API Entwicklern eine strukturierte Möglichkeit, programmgesteuert auf diese Funktion zuzugreifen und sie zu erweitern.
Mithilfe der API lassen sich Kommentar-Threads kontextspezifisch erstellen und verwalten, sodass Kommentare mit bestimmten Inhaltselementen wie Seiten oder Abschnitten verknüpft werden können. Dadurch wird sichergestellt, dass Feedback und Kommunikation eng mit den relevanten Inhalten verbunden bleiben, während gleichzeitig benutzerdefinierte Integrationen und erweiterte Arbeitsabläufe für die Zusammenarbeit ermöglicht werden, die über die Standardfunktionen der Benutzeroberfläche hinausgehen.
Die Collaboration-API unterstützt die folgenden Kernfunktionen:
- Erstellen und Verwalten von Kommentar-Threads
- Hinzufügen und Abrufen von Nachrichten in einer Unterhaltung
- Kontextbezogene Verknüpfung von Kommentar-Threads mit bestimmten Inhaltselementen
- Vollständiges Lebenszyklusmanagement, einschließlich Vorgängen zum Erstellen, Lesen, Aktualisieren, Archivieren und Wiederherstellen
- Mehrsprachige Unterstützung, die sprachspezifische Unterhaltungen ermöglicht
- Echtzeit-Aktualisierungen über WebSockets
- Validierung und Fehlerbehandlung zur Gewährleistung robuster Integrationen
)
.Beispiel-Anwendungsfälle
Threads erstellen und Kommentare hinzufügen
Das folgende Beispiel veranschaulicht die grundlegende Verwendung der Collaboration-API in FirstSpirit, indem ein neuer Thread erstellt und ein Kommentar hinzugefügt wird. Das Skript initialisiert zunächst die API über den Einstiegspunkt CollaborationAgents und erstellt einen ConversationPath, um den genauen Inhaltskontext zu definieren, in den der Thread eingefügt werden soll. Anhand dieses Pfads wird ein neuer Konversations-Thread erstellt und anschließend als aktueller Benutzer ein Kommentar zu diesem Thread hinzugefügt.
// Imports: FirstSpirit Imports
import de.espirit.firstspirit.agency.SpecialistsBroker;
// Imports: Collaboration API Imports
import com.crownpeak.firstspirit.modules.collaboration.agency.CollaborationAgents;
import com.crownpeak.firstspirit.modules.collaboration.agency.ConversationAgent;
import com.crownpeak.firstspirit.modules.collaboration.agency.IdentifierAgent;
import com.crownpeak.firstspirit.modules.collaboration.agency.MessageAgent;
import com.crownpeak.firstspirit.modules.collaboration.dto.conversation.Conversation;
import com.crownpeak.firstspirit.modules.collaboration.dto.conversation.ConversationPath;
import com.crownpeak.firstspirit.modules.collaboration.dto.conversation.Message;
// Required: SpecialistsBroker
// You can obtain a SpecialistsBroker using a Connection (connection.getBroker())
// or you can use 'context' in FirstSpirit scripts
SpecialistsBroker broker = /* ... */;
// Required: Project ID
long projectId = /* ... */;
// Obtain CollaborationAgents instance - This is the entry point for the Collaboration Java API
CollaborationAgents collaborationAgents = CollaborationAgents.create(broker);
// Create Conversation Path - used to locate a Conversation on an IDProvider
IdentifierAgent identifierAgent = collaborationAgents.getIdentifierAgent(projectId);
ConversationPath path = identifierAgent.createPathBuilder(/* IDProvider */)
.language(/* Language Code, e.g. "DE" */)
.editor(/* Editor Name, e.g. "pt_headline" */)
.build();
// Shows how to post a new Conversation using the ConversationPath we built earlier
// All messages will be posted as the current User
ConversationAgent conversationAgent = collaborationAgents.getConversationAgent(projectId);
Conversation conversation = conversationAgent.create(path, "Hello, World!");
// Shows how to post a new Message in our Conversation
MessageAgent messageAgent = collaborationAgents.getMessageAgent(projectId);
Message message = messageAgent.addMessage(conversation.getId(), "It's a wonderful day for Collaborating!");Threads und Kommentare abrufen
Dieses Beispiel zeigt, wie man mit der Collaboration-API in FirstSpirit vorhandene Threads und deren Kommentare nach einem bestimmten Inhaltselement durchsucht und überprüft. Das Skript initialisiert die erforderlichen Agenten, ermittelt die eindeutige Kennung (GID) eines IDProviders (z. B. einer Seite) und ruft alle zugehörigen Threads für eine bestimmte Sprache und einen bestimmten Archivstatus ab. Anschließend durchläuft es jeden Thread und ruft die entsprechenden Kommentare ab, wobei Details wie der Autor und der Kommentar-Inhalt ausgegeben werden.
// Imports: FirstSpirit Imports
import de.espirit.firstspirit.access.store.IDProvider;
import de.espirit.firstspirit.agency.SpecialistsBroker;
import de.espirit.firstspirit.common.GidAgent;
// Imports: Collaboration API Imports
import com.crownpeak.firstspirit.modules.collaboration.agency.CollaborationAgents;
import com.crownpeak.firstspirit.modules.collaboration.agency.ConversationAgent;
import com.crownpeak.firstspirit.modules.collaboration.agency.MessageAgent;
import com.crownpeak.firstspirit.modules.collaboration.dto.conversation.Conversation;
import com.crownpeak.firstspirit.modules.collaboration.dto.conversation.Message;
import java.util.*;
// Required: SpecialistsBroker
// You can obtain a SpecialistsBroker using a Connection (connection.getBroker())
// or you can use 'context' in FirstSpirit scripts
SpecialistsBroker broker = /* ... */;
// Required: Project ID
long projectId = /* ... */;
// Obtain CollaborationAgents instance - This is the entry point for the Collaboration Java API
CollaborationAgents collaborationAgents = CollaborationAgents.create(broker);
// Obtains the Collaboration API Agents
ConversationAgent conversationAgent = collaborationAgents.getConversationAgent(projectId);
MessageAgent messageAgent = collaborationAgents.getMessageAgent(projectId);
// Shows how to retrieve all Conversations for an IDProvider
IDProvider idProvider = ...; // The IDProvider, e.g., a PageRef
String language = ...; // e.g. "DE"
boolean archived = false; // Whether to fetch archived Conversations or non-archived Conversations
// Obtain the Gid of the IDProvider using GidAgent. The Collaboration API uses the Gid to find the IDProvider.
GidAgent gidAgent = broker.requireSpecialist(GidAgent.TYPE);
UUID elementGid = gidAgent.getGid(idProvider);
// Get the Conversations for the Element
List<Conversation> conversations = conversationAgent.getConversations(elementGid, language, archived);
System.out.println("Got " + conversations.size() + " conversations.");
// Iterate through all Conversations and show their Messages
for (Conversation conversation : conversations) {
System.out.println("Conversation:");
// Get Messages for Conversation and output their contents
List<Message> messages = messageAgent.getMessages(conversation.getId());
System.out.println("Conversation has " + messages.size() + " messages.");
for (Message message : messages) {
System.out.println("Message");
System.out.println(message.getAuthor().getDisplayName() + ":");
System.out.println(message.getContent());
System.out.println();
}
}