Automatisierungszentrale-API

  • Freigeben Version: Xanadu
  • Aktualisiert 1. August 2024
  • 10 Minuten Lesedauer

    • Die Automatisierungszentrale- API bietet Endpunkte zum Erstellen und Aktualisieren von Prozessen, Robots und Ausführungsaufträgen.

    Mit dieser API können Sie End-to-End-Automatisierungen für sich wiederholende Aufgaben definieren und diese Aufgaben dann verwalten und überwachen.

    Mit dieser API können Sie die folgenden Ereignistypen in Ihrer -Instanz ServiceNow erstellen:
    • Robots: Software-Agents, die einen Bot-Prozess ausführen. RPA-Robots können beaufsichtigt oder unbeaufsichtigt ausgeführt werden.
    • Prozess: Instanz einer RPA auf einem bestimmten Robot. Er ist für die Ausführung von Aufträgen verantwortlich. Um einen Prozess eindeutig zu identifizieren, müssen Sie sowohl die Prozess-ID als auch die Robot-ID angeben.
    • Ausführung: Bestimmte Aufgabe, die in einem Robot-Prozess ausgeführt werden soll, z. B. das Kopieren von Informationen aus einer Ressource und das Kopieren in eine andere, z. B. beim Kopieren von Informationen aus E-Mails in eine Tabelle.
    Sie können diese API beispielsweise verwenden, um die Entitäten zu definieren, die für die Anmeldung bei der Anwendung, das Kopieren und Einfügen von Informationen, das Verschieben von Dokumenten und Dateien und das Extrahieren von Inhalten aus E-Mails, PDFs und Formularen erforderlich sind.

    Normalerweise erstellen Sie zuerst einen Robot und dann alle Prozesse, die diesem Robot zugeordnet sind. Dies wird jedoch nicht von der API erzwungen. Sie müssen jedoch den Robot und den Prozess erstellen, bevor Sie versuchen, Aufträge für sie auszuführen, da sonst die Auftragsanforderung fehlschlägt.

    Hinweis:
    • Sie können ein Ereignis mit dieser API nicht löschen. Ereignisse werden standardmäßig nach 14 Tagen automatisch aus einer Instanz entfernt.
    • Sie können maximal 2.000 Datensätze pro Anruf übergeben. Dieser Wert kann nicht geändert werden.

    Diese API erfordert, dass das Plugin „Automatisierungszentrale“ aktiv ist, und erfordert, dass der Anwender 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

    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: 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.
    Mögliche 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 dann 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 dann 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 dann 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.

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

    Datentyp: Zeichenfolge
    Staat Nur Robot- und Ausführungsevent-Typen Status des zugeordneten Ereignisses.
    Mögliche 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):
    • Build
    • In Wartung
    • In Gebrauch
    • Stillgelegt
    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
    type Nur Ereignistypen „Prozess“ und „Robot“. Erforderlich für Prozess, optional für Robot. Typ der auszuführenden Verarbeitung.
    Mögliche 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-Antwortcodesder 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>": [
      "<field_in_err_or_missing>": "String"
    ]
  }
  "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 Parameter eventName ü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