Automatisierungszentrale-API

  • Freigeben Version: Yokohama
  • Aktualisiert 30. Januar 2025
  • 9 Minuten Lesedauer

    • Die API der Automatisierungszentrale bietet Endpunkte zum Erstellen und Aktualisieren von Daten im Zusammenhang mit Robots, Prozessen und Ausführungsaufträgen. Durch die Nutzung dieser API können Sie Details aus Ihren Automatisierungs-Workflows integrieren und im Dashboard Automatisierungszentrale integrieren.

    Schlüsselkonzepte der API:
    • Robots: Software-Agents, die Bot-Prozesse ausführen. RPA-Robots können im beaufsichtigten oder unbeaufsichtigten Modus arbeiten.
    • Prozesse: Instanzen von RPA-Workflows, die auf einem bestimmten Robot ausgeführt werden. Um einen Prozess eindeutig zu identifizieren, müssen sowohl die Prozess-ID als auch die Robot-ID angegeben werden.
    • Ausführungen: Einzelne Aufgaben, die innerhalb eines Prozesses ausgeführt werden, z. B. das Übertragen von Informationen von einer Ressource zu einer anderen (z. B. Kopieren von Daten aus E-Mails in eine Tabelle).

    So verwenden Sie die API:

    Sie können die API verwenden, um Daten von RPA-Tools von Drittparteien, einschließlich Robots, Prozessen und Ausführungen, an Automatisierungszentralezu senden.

    Empfohlener Workflow:
    1. Senden Sie die Robot-Daten.
    2. Senden Sie die mit dem gesendeten Robot verknüpften Prozessdaten.
    3. Senden Sie Ausführungsdaten, die auf den entsprechenden Robot und Prozess verweisen.
      Hinweis:
      Ausführungsdaten ohne den zugehörigen Robot und Prozess, die bereits in Automatisierungszentrale erfasst wurden, werden nicht im Dashboard angezeigt.
    Zusätzliche Informationen:
    • Ereignisaufbewahrung: Mit dieser API erstellte Ereignisse werden nach 14 Tagen (Standardeinstellung) automatisch aus Ihrer Instanz entfernt.
    • Datensatzgrenzen: Jeder API-Aufruf kann maximal 2.000 Datensätze verarbeiten. Dieser Grenzwert kann nicht geändert werden.
    • Event-Löschung: Diese API unterstützt das Löschen von Events nicht.

    Diese API erfordert, dass das Plugin Automatisierungszentrale aktiv ist und dass der -Benutzer entweder die Rolle „sn_as.automation_technical_user“ oder „sn_ac.automation_admin“ besitzt.

    Automatisierungszentrale – POST /sn_ac/automation/rpa

    Erstellt Robot-, Prozess- und Ausführungs-Ereignisse.

    Diese Ereignisse dienen zur Prozessautomatisierung. Sie werden in den Dashboards „Übersicht“ und „Ausführungsautomatisierungszentrale“ angezeigt, um die Ausgabe mehrerer RPA-Lieferanten zu messen und zu überwachen.

    URL-Format

    URL mit Versionsnummer: /api/sn_ac/{api_version}/automation/rpa

    Standard-URL: /api/sn_ac/v1/automation/rpa

    Hinweis:
    Verfügbare Versionen werden im REST-API-Explorerangegeben. Für geskriptete REST APIs finden Sie zusätzliche Versionsinformationen im Formular „Geskripteter REST-Service“.

    Unterstützte Anforderungsparameter

    Tabelle : 1. Pfadparameter
    Name Beschreibung
    api_version Optional. Version des Endpunkts, auf den zugegriffen werden soll. Zum Beispiel v1 oder v2. Geben Sie diesen Wert nur an, um eine andere Endpunktversion als die neueste zu verwenden.

    Datentyp: Zeichenfolge
    Tabelle : 2. Abfrageparameter
    Name Beschreibung
    Keine
    Tabelle : 3. Anforderungstextparameter (XML oder JSON)
    Name Beschreibung
    abteilungsname Nur Ereignistypen „Prozess“ und „Robot“. Name der Abteilung, zu der dieses Ereignis gehört.
    Dieser Wert wird je nach Ereignistyp in den folgenden Tabellen gespeichert:
    • Prozess: Feld „Abteilung“ in der Tabelle „Bot-Basisprozess“ [cmdb_ci_base_rpa_process]
    • Robot: Feld „Abteilung“ in der Tabelle „Basis-Robot“ [cmdb_ci_base_rpa_robot]

    Datentyp: Zeichenfolge
    domainId Sys_id der Domäne, zu der das Ereignis gehört.
    Dieser Wert wird je nach Ereignistyp in den folgenden Tabellen gespeichert:
    • „execution: sys_domain“ in der Tabelle „Automatisierungsausführung“ [sn_ac_automation_execution]
    • process: Feld „sys_domain“ in der Tabelle „Bot-Basisprozess“ [cmdb_ci_base_rpa_process].
    • Robot: Feld „sys_domain“ in der Tabelle „Basis-Robot“ [cmdb_ci_base_rpa_robot].

    Datentyp: Zeichenfolge
    endtime Nur Ausführungsereignistyp Endzeit der Ausführung. Dieser Wert wird im Feld end_time in der Tabelle „Automatisierungsausführung“ [sn_ac_automation_execution] gespeichert.

    Format: JJJJ-MM-TT HH:MM:SS

    Datentyp: Zeichenfolge
    Umgebung Nur Ausführungsereignistyp Umgebung der Ausführung, z. B. eine URL. Dieser Wert wird im Feld environment in der Tabelle „Automatisierungsausführung“ [sn_ac_automation_execution] gespeichert.
    Hinweis:
    Dieser Wert wird nicht von der Instanz ServiceNow verwendet und kann einen beliebigen für Ihre Implementierung erforderlichen Wert enthalten.

    Datentyp: Zeichenfolge
    errorMessage Nur Ausführungsereignistyp Name des Fehlermeldungsprotokolls. Dieser Wert wird im Nachrichtenfeld in der Tabelle „Automatisierungsausführung“ [sn_ac_automation_execution] gespeichert.

    Datentyp: Zeichenfolge
    eventName Erforderlich. Name des Ereignistyps. Dieser Wert bestimmt den Typ des zu verarbeitenden Ereignisses.
    Gültige Werte (Groß-/Kleinschreibung beachten):
    • Ausführung
    • process
    • Robot

    Datentyp: Zeichenfolge
    id Erforderlich. Eindeutiger numerischer Bezeichner des zugeordneten Ereignisses.
    Dieser Wert wird je nach Ereignistyp in den folgenden Tabellen gespeichert:
    • execute: Feld „automation_execution_id“ in der Tabelle „Automatisierungsausführung“ [sn_ac_automation_execution].
    • process: Feld „correlation_id“ in der Tabelle „Bot-Basisprozess“ [cmdb_ci_base_rpa_process]
    • Robot: Feld „correlation_id“ in der Tabelle „Basis-Robot“ [cmdb_ci_base_rpa_robot].

    Datentyp: Zahl (Ganzzahl)
    name Nur Ereignistypen „Prozess“ und „Robot“. Erforderlich Name des Events.
    Dieser Wert wird je nach Ereignistyp in den folgenden Tabellen gespeichert:
    • Prozess: Namensfeld in der Tabelle „Bot-Basisprozess“ [cmdb_ci_base_rpa_process]
    • Robot: Namensfeld in der Tabelle „Basis-Robot“ [cmdb_ci_base_rpa_robot].

    Datentyp: Zeichenfolge
    Priorität Nur Ausführungsereignistyp Priorität der Ausführung.
    Gültige Werte (Groß-/Kleinschreibung beachten):
    • Kritisch
    • Hoch
    • Mittel 
    • Niedrig
    Dieser Wert wird im Prioritätsfeld in der Tabelle „Automatisierungsausführung“ [sn_ac_automation_execution] gespeichert.

    Datentyp: Zeichenfolge

    Standard: Keine – Wird nicht im Dashboard angezeigt.
    processId Nur Ausführungsereignistyp Erforderlich Eindeutiger Bezeichner des Prozesses, für den die Ausführung ausgeführt werden soll. Dieser Wert befindet sich im Feld „correlation_id“ des entsprechenden Prozessdatensatzes in der Tabelle „Bot-Basisprozess“ [cmdb_ci_base_rpa_process].

    Dieser Wert wird im Automatisierungsfeld in der Tabelle „Automatisierungsausführung“ [sn_ac_automation_execution] gespeichert.

    Datentyp: Zeichenfolge
    RobotId Nur Ausführungsereignistyp Erforderlich Eindeutiger Bezeichner des Robots, auf dem die Ausführung ausgeführt werden soll. Dieser Wert befindet sich im Feld „correlation_id“ des entsprechenden Robot-Datensatzes in der Tabelle „Basis-Robot“ [cmdb_ci_base_rpa_robot].

    Dieser Wert wird im Robot-Feld in der Tabelle „Automatisierungsausführung“ [sn_ac_automation_execution] gespeichert.

    Datentyp: Zeichenfolge
    Quelle Erforderlich. Quelle, zu der das Ereignis gehört, z. B. „servicenow_rpa“. Dieser Wert befindet sich im Feld „internal_name“ der Tabelle „Automatisierungsquelle“ [sn_ac_automation_source].
    Dieser Wert wird je nach Ereignistyp in den folgenden Tabellen gespeichert:
    • execute: Quellfeld in der Tabelle „Automatisierungsausführung“ [sn_ac_automation_execution].
    • process: Quellfeld in der Tabelle „Bot-Basisprozess“ [cmdb_ci_base_rpa_process].
    • Robot: Quellfeld in der Tabelle „Basis-Robot“ [cmdb_ci_base_rpa_robot].

    Datentyp: Zeichenfolge
    starttime Nur Ausführungsereignistyp Startzeit der Ausführung. Dieser Wert wird im Feld start_time in der Tabelle „Automatisierungsausführung“ [sn_ac_automation_execution] gespeichert.

    Datentyp: Zeichenfolge

    Format: JJJJ-MM-TT HH:MM:SS
    state Nur Robot- und Ausführungsevent-Typen Status des zugeordneten Ereignisses.
    Gültige Werte für Robot (Groß-/Kleinschreibung beachten):
    • Storniert
    • Abgeschlossen
    • Fehler
    • In der Warteschlange
    • Wird ausgeführt
    Standard: In der Warteschlange
    Mögliche Werte für die Ausführung (Groß-/Kleinschreibung beachten):
    • Verfügbar
    • Beschäftigt
    • Verbindung getrennt
    • Neu
    • Reaktionsfähig
    Standard: Neu
    Dieser Wert wird je nach Ereignistyp in den folgenden Tabellen gespeichert:
    • execute: Statusfeld in der Tabelle „Automatisierungsausführung“ [sn_ac_automation_execution].
    • Robot: Feld „robot_state“ in der Tabelle „Basis-Robot“ [cmdb_ci_base_rpa_robot].

    Datentyp: Zeichenfolge
    status Nur Ereignistyp verarbeiten. Erforderlich Status des Prozesses.
    Mögliche Werte (Groß-/Kleinschreibung beachten):
    • Bauen
    • In Wartung
    • In Gebrauch
    • Deaktiviert
    Dieser Wert wird im Feld „life_cycle_stage_status“ in der Tabelle „Bot-Basisprozess“ [cmdb_ci_base_rpa_process] gespeichert.

    Datentyp: Zeichenfolge
    triggerBy Nur Ausführungsereignistyp Auslöserquelle der Ausführung. Dieser Wert wird im Feld trigger_by in der Tabelle „Automatisierungsausführung“ [sn_ac_automation_execution] gespeichert.
    Hinweis:
    Dieser Wert wird nicht von der Instanz ServiceNow verwendet und kann einen beliebigen für Ihre Implementierung erforderlichen Wert enthalten.

    Datentyp: Zeichenfolge
    Typ Nur Ereignistypen „Prozess“ und „Robot“. Erforderlich für Prozess, optional für Robot. Typ der auszuführenden Verarbeitung.
    Gültige Werte (Groß-/Kleinschreibung beachten):
    • Beaufsichtigt
    • Unbeaufsichtigt
    Dieser Wert wird je nach Ereignistyp in den folgenden Tabellen gespeichert:
    • process: Feld „process_type“ in der Tabelle „Bot-Basisprozess“ [cmdb_ci_base_rpa_process]
    • Robot: Feld „robot_type“ in der Tabelle „Basis-Robot“ [cmdb_ci_base_rpa_robot].

    Datentyp: Zeichenfolge

    Standard: Unattended für Robot
    version Nur Robot-Ereignistyp Version des Robots.

    Dieser Wert wird im Versionsfeld in der Tabelle „Basis-Robot“ [cmdb_ci_base_rpa_robot] gespeichert.

    Datentyp: Zeichenfolge

    Header

    Die folgenden Anforderungs- und Antwortkopfzeilen gelten nur für diese HTTP-Aktion oder für diese Aktion auf eine bestimmte Weise. Eine Liste der allgemeinen Header, die in der REST API verwendet werden, finden Sie unter Unterstützte REST API-Header.

    Tabelle : 4. Anforderungskopfzeilen
    Kopfzeile Beschreibung
    Akzeptieren Datenformat des Antworttexts. Unterstützte Typen: application/json oder application/xml.

    Standard: application/json
    Content-Type Datenformat des Anforderungstexts. Unterstützte Typen: application/json oder application/xml.

    Standard: application/json
    Tabelle : 5. Antwortkopfzeilen
    Kopfzeile Beschreibung
    Keine

    Statuscodes

    Die folgenden Statuscodes gelten für diese HTTP-Aktion. Eine Liste der möglichen Statuscodes, die in der REST API verwendet werden, finden Sie unter HTTP-Antwortcodes der REST-API.

    Tabelle : 6. Statuscodes
    Statuscode Beschreibung
    200 Erfolgreich. Die Anforderung wurde erfolgreich verarbeitet.
    400 Fehler. Die Anforderung wurde abgelehnt, da Pflichtfelder fehlen oder die Anforderung ungültige Werte enthält. In der zugehörigen Fehlermeldung wird der Fehlergrund beschrieben.

    Parameter des Antwort-Haupttexts

    Name Beschreibung
    Ergebnis Leer, wenn die Anforderung erfolgreich ist. Bei einem Fehler werden zusätzliche Informationen bereitgestellt.

    Datentyp: Objekt

    "result": {
  "fields": {
    "<record_number>": [Array]
  }
  "reason": "String"
}
    Wenn beispielsweise in den Datensätzen 1, 2 und 3 ein Pflichtfeld fehlt, wird eine Meldung ähnlich der folgenden zurückgegeben:
    {
  "result": {
    "fields": {
      "1": [
        "id"
      ],
      "2": [
        "status"
      ],
      "3": [
        "name"
      ]
    },
    "reason": "We are not able to process the data as following records have insufficient data"
  }
}

    cURL-Anforderung

    Das folgende Codebeispiel zeigt, wie drei Datensätze vom Typ „Robot-Ereignistyp“ veröffentlicht werden.

    curl "https://instance.servicenow.com/api/sn_ac/automation/rpa" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
  records: [{
    id: 8001,
    name: "Quotes system Automation Robot",
    state: "Available",
    status: "In Use",
    version: 5.6,
    departmentName: "Customer Support",
    type: "Unattended",
    source: "servicenow_rpa",
    eventName: "robot"
  },
  {
    id: 8002,
    name: "Invoice Matching Robot",
    state: "Responsive",
    status: "In Maintenance",
    version: 3,
    departmentName: "HR",
    type: "Unattended",
    source: "servicenow_rpa",
    eventName: "robot"
  },
  {
    id: 8003,
    name: "Data Reconciliation Robot",
    state: "Busy",
    status: "Retired",
    version: 2,
    departmentName: "Finance",
    type: "Unattended",
    source: "servicenow_rpa",
    eventName: "robot"
  }]
} "\
--user "username":"password"

    Dieser Endpunkt gibt nur bei Erfolg einen HTTP-Statuscode und bei einem Fehler einen HTTP-Statuscode und eine Fehlermeldung zurück.

    None

    cURL-Anforderung

    Das folgende Codebeispiel zeigt, wie drei Datensätze vom Typ „Prozessereignis“ veröffentlicht werden.

    curl "https://instance.servicenow.com/api/sn_ac/automation/rpa" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
  records: [{
    id: 9001,
    name: "RPA Execution Process",
    status: "In Maintenance",
    type: "Attended",
    departmentName: "Customer Support",
    source: "servicenow_rpa",
    eventName: "process"
  },
  {
    id: 9002,
    name: "Customer Onboarding",
    status: "In Use",
    type: "Attended",
    departmentName: "Finance",
    source: "servicenow_rpa",
    eventName: "process"
  },
  {
    id: 9003,
    name: "Data Reconciliation",
    status: "Retired",
    type: "Unattended",
    departmentName: "HR",
    source: "servicenow_rpa",
    eventName: "process"
  }]
}" \
--user "username":"password"

    Dieser Endpunkt gibt nur bei Erfolg einen HTTP-Statuscode und bei einem Fehler einen HTTP-Statuscode und eine Fehlermeldung zurück.

    None

    cURL-Anforderung

    Das folgende Codebeispiel zeigt, wie drei Datensätze vom Typ „Ausführungsereignis“ veröffentlicht werden.

    curl "https://instance.servicenow.com/api/sn_ac/automation/rpa" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
  records: [{
    id: 7001,
    name: "Customer Onboarding",
    starttime: "2022-03-18 00:49:13",
    endtime: "2022-03-20 00:58:03",
    state: "Running",
    priority: "Critical",
    environment: "system",
    triggeredBy: "Schedule",
    processId: 9001,
    robotId: 8001,
    source: "servicenow_rpa",
    eventName: "execution"
  },
  {
    id: 7002,
    name: "Data Reconciliation",
    starttime: "2022-04-30 00:19:11",
    endtime: "2022-05-02 00:41:35",
    state: "Error",
    priority: "Low",
    environment: "system",
    triggeredBy: "API",
    processId: 9002,
    robotId: 8002,
    source: "servicenow_rpa",
    eventName: "execution"
  },
  {
    id: 7003,
    name: "Customer Onboarding",
    starttime: "2022-01-22 02:38:53",
    endtime: "2022-01-23 02:50:44",
    state: "Queued",
    priority: "Moderate",
    environment: "system",
    triggeredBy: "Schedule",
    processId: 9003,
    robotId: 8003,
    source: "servicenow_rpa",
    eventName: "execution"
  }]
} "\
--user "username":"password"

    Dieser Endpunkt gibt nur bei Erfolg einen HTTP-Statuscode und bei einem Fehler einen HTTP-Statuscode und eine Fehlermeldung zurück.

    None

    cURL-Anforderung

    Das folgende Codebeispiel zeigt, wie Sie einen -Prozess erstellen oder aktualisieren. Sie erstellen einen Prozess, indem Sie alle obligatorischen Parameter für die Ausführung eines Prozesses übergeben, wobei eventName auf „process“ festgelegt ist. Die folgenden Pflichtparameter sind zum Erstellen eines Prozesses erforderlich: id, type, status, nameund source.

    curl "https://instance.servicenow.com/api/sn_ac/automation/rpa" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
records: [{
id: 9001,
name: "RPA Execution Process",
status: "In Maintenance",
type: "Attended",
departmentName: "Customer Support",
source: "servicenow_rpa",
eventName: "process"
}]
} "\
--user "username":"password"

    Dieser Endpunkt gibt nur bei Erfolg einen HTTP-Statuscode und bei einem Fehler einen HTTP-Statuscode und eine Fehlermeldung zurück.

    None

    cURL-Anforderung

    Das folgende Codebeispiel zeigt, wie ein -Prozess veröffentlicht wird. Sie können einen Prozess veröffentlichen, indem Sie den Parameter status auf „Veröffentlicht“ setzen.

    curl "https://instance.servicenow.com/api/sn_ac/automation/rpa" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
records: [{
id: 9002,
name: "RPA Execution Process",
status: "Published",
type: "Attended",
departmentName: "Customer Support",
source: "servicenow_rpa",
eventName: "process"
}]
} "\
--user "username":"password"

    Dieser Endpunkt gibt nur bei Erfolg einen HTTP-Statuscode und bei einem Fehler einen HTTP-Statuscode und eine Fehlermeldung zurück.

    None

    cURL-Anforderung

    Das folgende Codebeispiel zeigt, wie Sie einen Robot erstellen oder aktualisieren. Sie erstellen einen Robot, indem Sie alle obligatorischen Parameter für einen Robot zusammen mit eventName übergeben, das auf „robot“ festgelegt ist. Die obligatorischen Parameter zum Erstellen eines Robots sind: id, status, nameund source.

    curl "https://instance.servicenow.com/api/sn_ac/automation/rpa" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
records: [{
id: 8001,
name: "Quotes system Automation Robot",
state: "Available",
status: "In Use",
version: 5.6,
departmentName: "Customer Support",
type: "Unattended",
source: "servicenow_rpa",
eventName: "robot"
} "\
--user "username":"password"

    Dieser Endpunkt gibt nur bei Erfolg einen HTTP-Statuscode und bei einem Fehler einen HTTP-Statuscode und eine Fehlermeldung zurück.

    None

    cURL-Anforderung

    Das folgende Codebeispiel zeigt, wie Sie eine -Ausführung erstellen oder aktualisieren. Sie erstellen eine Ausführung, indem Sie alle obligatorischen Parameter für eine Ausführung zusammen mit dem eventName Parameter übergeben, der auf „execution“ festgelegt ist. Die folgenden Pflichtparameter sind zum Erstellen einer Ausführung erforderlich: id, processId, robotIdund source.

    curl "https://instance.servicenow.com/api/sn_ac/automation/rpa" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
records: [{
id: 7001,
name: "Customer Onboarding",
starttime: "2022-03-18 00:49:13",
endtime: "2022-03-20 00:58:03",
state: "Running",
priority: "Critical",
environment: "http://acqa.servicenow.com",
triggeredBy: "Schedule",
processId: 9001,
robotId: 8001,
source: "servicenow_rpa",
eventName: "execution",
errorMessage:"Error due to Inactivity"
}]
} "\
--user "username":"password"

    Dieser Endpunkt gibt nur bei Erfolg einen HTTP-Statuscode und bei einem Fehler einen HTTP-Statuscode und eine Fehlermeldung zurück.

    None