Projektaktivität

Abrufen und Überwachen von Projektaktivitätsfeeds mit der Blue API.

Projektaktivität abrufen

Die activityList-Abfrage bietet Zugriff auf einen umfassenden Aktivitätsfeed für Projekte und Unternehmen. Aktivitäten werden automatisch generiert, wenn Benutzer Aktionen wie das Erstellen von To-dos, Kommentaren oder das Ändern von Projekten durchführen.

Einfaches Beispiel

query ProjectActivity {
  activityList(
    projectId: "your-project-id"
    first: 20
    orderBy: createdAt_DESC
  ) {
    activities {
      id
      category
      html
      createdAt
      createdBy {
        id
        name
        email
      }
      project {
        id
        name
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
    totalCount
  }
}

Fortgeschrittenes Beispiel mit Filterung

query FilteredActivity {
  activityList(
    companyId: "your-company-id"
    categories: [CREATE_TODO, MARK_TODO_AS_COMPLETE, CREATE_COMMENT]
    userIds: ["user1-id", "user2-id"]
    startDate: "2024-01-01T00:00:00Z"
    endDate: "2024-12-31T23:59:59Z"
    first: 50
    orderBy: createdAt_DESC
  ) {
    activities {
      id
      uid
      category
      html
      createdAt
      updatedAt
      createdBy {
        id
        name
        email
      }
      affectedBy {
        id
        name
      }
      todo {
        id
        title
      }
      comment {
        id
        text
      }
      project {
        id
        name
        slug
      }
    }
    pageInfo {
      hasNextPage
      hasPreviousPage
      startCursor
      endCursor
    }
    totalCount
  }
}

Eingabeparameter

activityList-Abfrage

Parameter	Typ	Erforderlich	Beschreibung
`companyId`	String	Nein	Aktivitäten nach Unternehmens-ID oder Slug filtern
`projectId`	String	Nein	Aktivitäten nach Projekt-ID oder Slug filtern
`userId`	String	Nein	Aktivitäten nach einem bestimmten Benutzer filtern
`userIds`	[String!]	Nein	Aktivitäten nach mehreren Benutzern filtern
`tagIds`	[String!]	Nein	Aktivitäten nach To-do-Tags filtern
`categories`	[ActivityCategory!]	Nein	Nach bestimmten Aktivitätstypen filtern
`startDate`	DateTime	Nein	Aktivitäten ab diesem Datum filtern
`endDate`	DateTime	Nein	Aktivitäten bis zu diesem Datum filtern
`skip`	Int	Nein	Diese Anzahl von Datensätzen überspringen (Offset-Paginierung)
`first`	Int	Nein	Erste N Datensätze zurückgeben (Cursor-Paginierung)
`last`	Int	Nein	Letzte N Datensätze zurückgeben (Cursor-Paginierung)
`after`	String	Nein	Datensätze nach diesem Cursor zurückgeben
`before`	String	Nein	Datensätze vor diesem Cursor zurückgeben
`orderBy`	ActivityOrderByInput	Nein	Sortierreihenfolge für Ergebnisse

ActivityCategory-Werte

Das System verfolgt automatisch verschiedene Arten von Aktivitäten:

Kategorie	Beschreibung
`CREATE_TODO`	Ein neues To-do/Aufgabe wurde erstellt
`MARK_TODO_AS_COMPLETE`	Ein To-do wurde als abgeschlossen markiert
`CREATE_COMMENT`	Ein Kommentar wurde hinzugefügt
`CREATE_DISCUSSION`	Eine Diskussion wurde gestartet
`CREATE_STATUS_UPDATE`	Ein Statusupdate wurde gepostet
`CREATE_TODO_LIST`	Eine neue To-do-Liste wurde erstellt
`MOVE_TODO`	Ein To-do wurde zwischen Listen verschoben
`COPY_TODO`	Ein To-do wurde kopiert
`ADD_USER_TO_PROJECT`	Ein Benutzer wurde dem Projekt hinzugefügt
`REMOVE_USER_FROM_PROJECT`	Ein Benutzer wurde aus dem Projekt entfernt
`ARCHIVE_PROJECT`	Das Projekt wurde archiviert
`UNARCHIVE_PROJECT`	Das Projekt wurde wiederhergestellt
`CREATE_INVITATION`	Ein Benutzer wurde eingeladen
`ACCEPT_INVITATION`	Eine Einladung wurde angenommen
`CREATE_CUSTOM_FIELD`	Ein benutzerdefiniertes Feld wurde erstellt
`RECEIVE_FORM`	Eine Formularübermittlung wurde empfangen

ActivityOrderByInput-Werte

Wert	Beschreibung
`createdAt_DESC`	Neueste zuerst (Standard)
`createdAt_ASC`	Älteste zuerst
`updatedAt_DESC`	Zuletzt aktualisiert zuerst
`updatedAt_ASC`	Am wenigsten kürzlich aktualisiert zuerst
`category_ASC`	Alphabetisch nach Kategorie
`category_DESC`	Umgekehrt alphabetisch nach Kategorie

Antwortfelder

Aktivitätstyp

Feld	Typ	Beschreibung
`id`	ID!	Eindeutiger Identifikator für die Aktivität
`uid`	String!	Alternativer eindeutiger Identifikator
`category`	ActivityCategory!	Art der aufgetretenen Aktivität
`html`	String!	Rich-HTML-Beschreibung der Aktivität
`createdAt`	DateTime!	Wann die Aktivität stattfand
`updatedAt`	DateTime!	Wann die Aktivität zuletzt aktualisiert wurde
`createdBy`	User!	Benutzer, der die Aktion ausgeführt hat
`affectedBy`	User	Benutzer, der von der Aktion betroffen war
`company`	Company	Zugehöriges Unternehmen
`project`	Project	Zugehöriges Projekt
`todo`	Todo	Zugehöriges To-do (falls zutreffend)
`todoList`	TodoList	Zugehörige To-do-Liste (falls zutreffend)
`comment`	Comment	Zugehöriger Kommentar (falls zutreffend)
`discussion`	Discussion	Zugehörige Diskussion (falls zutreffend)
`statusUpdate`	StatusUpdate	Zugehöriges Statusupdate (falls zutreffend)
`metadata`	String	Zusätzliche Aktivitätsmetadaten

ActivityList-Antwort

Feld	Typ	Beschreibung
`activities`	[Activity!]!	Array von Aktivitätsdatensätzen
`pageInfo`	PageInfo!	Paginierungsinformationen
`totalCount`	Int!	Gesamtzahl der Aktivitäten, die den Filtern entsprechen

Echtzeit-Aktivitätsupdates

Abonnieren Sie Aktivitätsänderungen mit dem subscribeToActivity-Abonnement:

subscription ActivityUpdates($companyId: String!, $projectId: String) {
  subscribeToActivity(companyId: $companyId, projectId: $projectId) {
    mutation
    node {
      id
      category
      html
      createdAt
      createdBy {
        id
        name
        email
      }
      project {
        id
        name
      }
    }
  }
}

Abonnementparameter

Parameter	Typ	Erforderlich	Beschreibung
`companyId`	String	Nein	Abonnieren Sie unternehmensweite Aktivitäten
`projectId`	String	Nein	Abonnieren Sie spezifische Projektaktivitäten

Das Abonnement benachrichtigt Sie über:

ACTIVITY_CREATED - Neue Aktivitäten
ACTIVITY_UPDATED - Geänderte Aktivitäten
ACTIVITY_DELETED - Entfernte Aktivitäten

Filterung und Datenschutz

Automatische Filterung

Der Aktivitätsfeed filtert Ergebnisse automatisch basierend auf:

Projekteinstellungen: Zeigt nur Aktivitäten von Projekten mit aktivierter Aktivitätsverfolgung an
Benutzerberechtigungen: Verschiedene Benutzerrollen sehen unterschiedliche Aktivitätstypen
Projektmitgliedschaft: Benutzer sehen nur Aktivitäten von Projekten, auf die sie Zugriff haben
Unternehmensmitgliedschaft: Aktivitäten sind auf die Unternehmen des Benutzers beschränkt

Datenschutzüberlegungen

CLIENT-Rollenbenutzer haben eingeschränkte Sichtbarkeit auf bestimmte administrative Aktivitäten
Aktivitäten respektieren die Datenschutzeinstellungen auf Projektebene
Sensible Operationen generieren möglicherweise keine öffentlichen Aktivitäten

Fehlerantworten

Ungültiges Projekt/Unternehmen

{
  "errors": [{
    "message": "Project not found",
    "extensions": {
      "code": "NOT_FOUND"
    }
  }]
}

Berechtigung verweigert

{
  "errors": [{
    "message": "You do not have permission to view activities for this project",
    "extensions": {
      "code": "FORBIDDEN"
    }
  }]
}

Ungültiger Datumsbereich

{
  "errors": [{
    "message": "Start date must be before end date",
    "extensions": {
      "code": "BAD_USER_INPUT"
    }
  }]
}

Beste Praktiken

Verwenden Sie Paginierung: Aktivitätsfeeds können groß sein, verwenden Sie immer den first-Parameter
Filtern nach Projekt: Unternehmensweite Aktivitätsfeeds können überwältigend sein
Echtzeit-Updates: Verwenden Sie Abonnements für Live-Aktivitätsfeeds
Datumsfilterung: Verwenden Sie Datumsbereiche für historische Aktivitätsanalysen
Kategoriefilterung: Filtern Sie nach bestimmten Aktivitätstypen für fokussierte Feeds
Benutzerfilterung: Verfolgen Sie die Aktivitäten bestimmter Teammitglieder mit userIds

Wichtige Hinweise

Aktivitäten werden automatisch generiert und können nicht manuell über die API erstellt werden
Aktivitätstexte verwenden HTML-Formatierung für eine reichhaltige Anzeige
Das text-Feld ist veraltet zugunsten von html
Aktivitäten werden dauerhaft gespeichert und bieten eine vollständige Prüfspur
Echtzeit-Abonnements erfordern die Authentifizierung der WebSocket-Verbindung