Automation Center-API

  • Freigeben Version: Washingtondc
  • Aktualisiert 1. Februar 2024
  • 9 Minuten Lesedauer

    • Mit der Automation Center-API können Sie Prozesse, Robots und Ausführungsaufträge erstellen und aktualisieren.

    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 Arten von Events in Ihrer ServiceNow -Instanz erstellen:
    • Robots: Software-Agents, die einen Bot-Prozess ausführen. RPA-Robots können beaufsichtigt oder unbeaufsichtigt ausgeführt werden.
    • Prozess: Instanz eines 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: Spezifische Aufgabe, die in einem Robot-Prozess ausgeführt werden soll, z. B. das Kopieren von Informationen aus einer Ressource in eine andere, z. B. beim Kopieren von Informationen aus E-Mails in eine Tabelle.
    Beispielsweise können Sie diese API verwenden, um die erforderlichen Entitäten zu definieren, um sich bei der Anwendung anzumelden, Informationen zu kopieren und einzufügen, Dokumente und Dateien zu verschieben und Inhalte aus E-Mails, PDFs und Formularen zu extrahieren.

    Normalerweise sollten Sie zuerst einen Robot und dann alle diesem Robot zugeordneten Prozesse erstellen. Dies wird jedoch von der API nicht 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 Event nicht mit dieser API löschen. Events werden standardmäßig nach 14 Tagen automatisch aus einer Instanz entfernt.
    • Sie können maximal 2.000 Datensätze pro Aufruf übergeben. Dieser Wert kann nicht geändert werden.

    Für diese API muss das Plugin „Automation Center“ aktiv sein, und der Benutzer muss entweder über die Rolle „sn_as.automation_technical_user“ oder „sn_ac.automation_admin“ verfügen.

    Automation Center – POST /sn_ac/automation/rpa

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

    Diese Events bieten Prozessautomatisierung. Sie werden in den Dashboards „Übersicht“ und „Execution Automation Center“ angezeigt, um die Ausgabe mehrerer RPA-Lieferanten zu messen und zu überwachen.

    URL-Format

    Versionierte URL: /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 das Ereignis gehört.
    Dieser Wert wird abhängig vom Event-Typ in den folgenden Tabellen gespeichert:
    • process: Feld „department“ in der Tabelle „Bot-Basisprozess“ [cmdb_ci_base_rpa_process].
    • Robot: Feld „Department“ in der Tabelle „Basis-Robot“ [cmdb_ci_base_rpa_robot].

    Datentyp: Zeichenfolge
    domainId Sys_id der Domäne, zu der das Event gehört.
    Dieser Wert wird abhängig vom Event-Typ in den folgenden Tabellen gespeichert:
    • execute: sys_domain-Feld in der Automatisierungsausführungstabelle [sn_ac_automation_execution].
    • process: sys_domain-Feld 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 Umgebungsfeld in der Tabelle „Automatisierungsausführung“ [sn_ac_automation_execution] gespeichert.
    Hinweis:
    Dieser Wert wird nicht von der Instanz ServiceNow verwendet und kann einen beliebigen Wert enthalten, der für Ihre Implementierung erforderlich ist.

    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 Event-Typs. Dieser Wert bestimmt den Typ des zu verarbeitenden Events.
    Gültige Werte (Groß-/Kleinschreibung beachten):
    • Ausführung
    • process
    • Robot

    Datentyp: Zeichenfolge
    id Erforderlich. Eindeutiger numerischer Identifier des zugeordneten Events.
    Dieser Wert wird abhängig vom Event-Typ in den folgenden Tabellen gespeichert:
    • Ausführung: 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 abhängig vom Event-Typ in den folgenden Tabellen gespeichert:
    • process: name-Feld 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
    Robot-ID 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 Feld „Robot“ in der Tabelle „Automatisierungsausführung“ [sn_ac_automation_execution] gespeichert.

    Datentyp: Zeichenfolge
    Quelle Erforderlich. Quelle, zu der das Event 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 abhängig vom Event-Typ 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
    Status Nur Robot- und Ausführungs-Event-Typen. Status des zugeordneten Events.
    Mögliche Werte für Robot (Groß-/Kleinschreibung beachtet):
    • Storniert
    • Abgeschlossen
    • Fehler
    • In der Warteschlange
    • Wird ausgeführt
    Standard: In der Warteschlange
    Mögliche Werte für die Ausführung (Groß-/Kleinschreibung beachtet):
    • Verfügbar
    • Beschäftigt
    • Verbindung getrennt
    • Neu
    • Reaktionsfähig
    Standard: Neu
    Dieser Wert wird abhängig vom Event-Typ in den folgenden Tabellen gespeichert:
    • Ausführung: 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 Event-Typ verarbeiten. Erforderlich. Status des Prozesses.
    Mögliche Werte (Groß-/Kleinschreibung beachten):
    • Build
    • 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
    ausgelöst von 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 Wert enthalten, der für Ihre Implementierung erforderlich ist.

    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 abhängig vom Event-Typ 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: Unbeaufsichtigt 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 fehlten oder die Anforderung ungültige Werte enthielt. Die zugehörige Fehlermeldung beschreibt den Grund für den Fehler.

    Parameter des Antwort-Haupttexts

    Name Beschreibung
    Ergebnis Leer, wenn die Anforderung erfolgreich ist. Für Fehler werden zusätzliche Informationen bereitgestellt.

    Datentyp: Objekt

    "result": {
  "fields": {
    "<record_number>": [
      "<field_in_err_or_missing>": "String"
    ]
  }
  "reason": "String"
}
    Beispiel: Wenn 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 Robot-Event-Typ-Datensätze 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 Prozessereignistyp-Datensätze 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 Ausführungsereignistyp-Datensätze 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 ein Prozess erstellt oder aktualisiert wird. Sie erstellen einen Prozess, indem Sie alle obligatorischen Parameter für die Ausführung eines Prozesses übergeben, wobei eventName auf „process“ festgelegt ist. Die zum Erstellen eines Prozesses erforderlichen obligatorischen Parameter sind: 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 übergeben, der auf „Veröffentlicht“ festgelegt ist.

    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 ein Robot erstellt oder aktualisiert wird. Sie erstellen einen Robot, indem Sie alle obligatorischen Parameter für einen Robot übergeben und eventName auf „robot“ setzen. Die zum Erstellen eines Robots erforderlichen obligatorischen Parameter 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 eine Ausführung erstellt oder aktualisiert wird. Sie erstellen eine Ausführung, indem Sie alle obligatorischen Parameter für eine Ausführung übergeben und eventName auf „execution“ setzen. Die zum Erstellen einer Ausführung erforderlichen Pflichtparameter sind: 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