Connect Solutions - REST API für den SAP Solution Manager
Endpunkte (REST API für den SAP Solution Manager)
In diesem Kapitel werden die zur Verfügung stehenden Endpunkte des Connect Solution Manager Addons beschrieben. Die Basis-URL der Endpunkte setzt sich aus dem verwendeten Protokoll (http oder https), dem Hostnamen, des Ports und des Service wie folgt zusammen:
http(s)://<sap_hostname>:<sap_port>/gal/solman/api/rest/1/
Informationen zu den Hostnamen und Ports Ihres Solution Managers können Sie über die Transaktion SICF einsehen, indem im Menü „Springen“ der Eintrag „Port Information“ ausgewählt wird.
Die Endpunkte können auch über die Connect Applikation durchgereicht werden. Die effektiven Endpunkte würden dann im Wesentlichen wie folgt aussehen:
http(s)://<connect_hostname>:<connect_port>/repositories/<repository_name>/connections/<connection_name>/events/<event_name>.
Pfad- und Query-Parameter werden beim Aufruf von Webservices über die Connect Applikation als Query-Parameter übergeben. Die Query-Parameter müssen grundsätzlich im Camel Case Format übergeben werden. Existiert bei einem SAP-Endpunkt beispielsweise der Pfad-Parameter „object_id“, muss dieser über die Connect Applikation als Query-Parameter „objectId“ übergeben werden.
Beispiel-Response für den Knoten “requests”:
GET /data/external_ids/{external_id}
Der Endpunkt GET /data/external_ids/{external_id} liefert dieselben Informationen wie der Endpunkt GET /data/objects/{object_id} nur mit dem Unterschied, dass das Objekt anhand der verknüpften Externen ID ermittelt wird.
GET /data/objects/{object_id}/children
Dieser Endpunkt liefert anhand einer Objekt ID alle zugeordneten verknüpften Objekte, z. B. wenn die Objekt ID einer Änderungsantrag-ID entspricht, liefert der Endpunkt Informationen zu den verknüpften Änderungsdokumenten.
Der Endpunkt liefert folgende Informationen in tabellarischer Form.
Name | Typ | Beschreibung |
parentGuid | Wert | Global eindeutige ID dessen zugeordnete Objekte angefordert wurden |
parentObjectId | Wert | Objekt ID |
parentProcessType | Wert | Vorgangsart |
totalChildren | Wert | Anzahl der zugeordneten Objekte |
children | Array | Liste mit Details zu den zugeordneten Objekten |
Tabellarische Ansicht der Informationen innerhalb des „children“ Arrays.
Name | Typ | Beschreibung |
guid | Wert | Global eindeutige ID |
objectId | Wert | Objekt ID |
processType | Wert | Vorgangsart |
description | Wert | Kurzbeschreibung |
userStatus | Wert | Aktueller Status |
userStatusText | Wert | Beschreibung des aktuellen Status |
userStatusFinal | Wert | Kennzeichen („X“ = True, „“ = False), ob der aktuelle Status nicht mehr geändert werden kann. |
Beispiel-Response:
GET /data/external_ids/{external_id}/children
Dieser Endpunkt liefert identische Informationen wie der Endpunkt GET /data/objects/{object_id}/children mit dem Unterschied, dass das übergeordnete Objekt mithilfe der Externen ID ermittelt wird.
GET /data/objects/{object_id}/action
Dieser Endpunkt liefert anhand einer spezifizierten Objekt ID Informationen der verfügbaren PPF-Aktionen des zum Objekt gehörigen Aktionsprofils. Zusätzlich liefert der Endpunkt für jede PPF-Aktion ein Kennzeichen, ob die Aktion zum aktuellen Status ausgeführt werden kann.
Die PPF-Aktionen finden Sie im Customizing mithilfe der Transaktion SPRO über den Pfad „SAP Solution Manager -> Capabilities (Optional) -> Change-Control-Management -> Vorgänge -> Aktionen -> Aktionen und Bedingungen ändern -> Aktionsprofile und Aktionen definieren“. Das Aktionsprofil für ChaRM Vorgänge lauten in der Regel <Vorgangsart>_ACTIONS, z. B. ZMCR_ACTIONS. Über den Customizing Pfad „SAP Solution Manager -> Capabilities (Optional) -> Change-Control-Management -> Vorgänge -> Aktionen -> Aktionsprofil der Vorgangsart zuordnen“ kann zusätzlich genau feststellen wie das Aktionsprofil eine bestimmten Vorgangsart lautet.
Der Endpunkt liefert ein paar Informationen zu der angeforderten Objekt ID und ein Array mit den PPF-Aktionen, die wie folgt aussehen.
Name | Typ | Beschreibung |
actions | Array | Liste der verfügbaren Objektaktionen |
description | Wert | Kurzbeschreibung |
externalID | Wert | Externe ID, sofern existent |
objectGuid | Wert | Global eindeutige ID |
objectId | Wert | Objekt ID |
processType | Wert | Vorgangsart |
Die Elemente des Arrays „actions“ enthalten folgende Informationen zu PPF-Aktionen.
Name | Typ | Beschreibung |
guid | Wert | Global eindeutige ID der PPF-Aktionen |
ttype | Wert | Name |
ttypedescr | Wert | Kurzbeschreibung |
context | Wert | Aktionsprofil |
executable | Wert | Kennzeichen, ob die PPF-Aktion für den aktuellen Objektstatus ausgeführt werden kann. Der Wert „X“ entspricht „True“ und der Wert „“ entspricht „False“. |
Bespiel-Response:
GET /data/external_ids/{external_id}/action
Dieser Endpunkt liefert die selben Informationen anhand einer Externen ID zu PPF-Aktionen eines bestimmten Objekts wie der Endpunkt GET /data/objects/{object_id}/action.
GET /data/objects/search
Dieser Endpunkt dient zur Suche nach Objekten im Solution Manager anhand von vordefinierter Filterkriterien.
Die Filterkriterien werden bei diesem Endpunkt komplett als Query-Parameter übergeben. Folgende Query-Parameter können angegeben werden.
Name | Mögliche Werte | Beschreibung |
description | Beliebiger Text ohne Berücksichtigung der Groß- und Kleinschreibung. Als Ersetzungszeichen für musterbasierte Suche können „*“ und „%“ verwendet werden. | Objektbeschreibung |
only_active_status | „true“ oder „false“ | Nur nicht finale Objekte bei der Suche berücksichtigen |
object_id | 10stellige Objektnummer. Eine Musterbasierte Suche ist unter Angabe von „*“ oder „%“ möglich. | Objekt ID |
configuration_item | Das Konfigurations-Element als Zeichenkette. Eine Musterbasierte Suche für das Konfigurations-Element ist nicht möglich. | Konfigurationselement |
product_id | Das Konfigurations-Element als Zeichenkette. Eine Musterbasierte Suche für das Konfigurations-Element ist nicht möglich. | Konfigurationselement (alternativer Name) |
posting_date | Datumsangabe in der Form YYYY-MM-DD | Erstellungsdatum |
object_type | Folgende Festwerte sind erlaubt: | Objekttyp |
Die Antwort des Endpunktes entspricht der nachfolgenden Tabelle.
Name | Typ | Beschreibung |
totalObjects | Wert | Anzahl der gefundenen Objekte |
objects | Array | Objektliste der gefundenen Objekte |
Die Objekte aus dem Array „objects“ enthalten dabei folgende Werte.
Name | Typ | Beschreibung |
guid | Wert | Global eindeutige ID |
objectId | Wert | Objekt ID |
processType | Wert | Vorgangsart |
postingDate | Wert | Anlagedatum |
description | Wert | Objektbeschreibung |
userStatus | Wert | Aktueller Status |
userStatusText | Wert | Beschreibung des aktuellen Status |
userStatusFinal | Wert | Kennzeichen („X“ = True, „“ = False), ob der aktuelle Status nicht mehr geändert werden kann. |
configItem | Wert | Konfigurationselement, falls das Objekt kein Änderungszyklus ist |
configItemText | Wert | Konfigurationselementbeschreibung, falls Objekt kein Änderungszyklus ist |
cycleId | Wert | Objekt ID des zugehörigen Änderungszyklus |
cycleText | Wert | Beschreibung des zugehörigen Änderungszyklus |
totalCycleConfigItems | Wert | Anzahl zugeordneter Konfigurationselementen, falls Objekt ein Änderungszyklus ist |
cycleConfigItems | Array | Liste zugeordneten Konfigurationselementen, falls Objekte ein Änderungszyklus ist |
Die Elemente aus dem Feld „cycleConfigItems“ entsprechen dem folgenden Format:
Name | Typ | Beschreibung |
configItem | Wert | Konfigurationselement |
configItemText | Wert | Konfigurationselementbeschreibung |
Beispiel-Response:
POST /data
Mithilfe dieses Endpunkts können neue Objekte im Solution Manager angelegt werden. Der Endpunkt akzeptiert zusätzlich den Query-Parameter „simulation“, um eine Anlage eines Objekts zu simulieren. Um eine Anlage zu simulieren, muss dem Parameter entweder der Wert “True” oder “X” zugeordnet werden, z. B. “http(s)//: … /data?simulation=True”
Der Request muss mindestens einen Wert für die Vorgangsart über die Eigenschaft “processType” enthalten, um ein Objekt anlegen zu können.
Die nachfolgenden Objektwerte werden aktuell unterstützt, wenn diese im Request enthalten sind.
Konfigurationselement
Das Konfigurationselement oder IBase-Komponente ist ein JSON Objekt mit Namen “configurationItem” mit den Eigenschaften “productId” für das Konfigurationselement und “textIbComp” für die Beschreibung des Konfigurationselements, wobei für die Anlage oder Änderung nur der Wert für “productId” relevant ist.
Kundeneigene Felder
Alle Kundeneigenen Felder, die in der Tabelle CRMD_CUSTOMER_H existieren und entweder mit ZZ oder YY beginnen, können bei der Objektanlage übergeben werden.
Wenn Beispielsweise das kundeneigene Feld ZZEXTERNAL_URI die URL eines verknüpften Jira Issue enthalten soll, kann folgendes im Request übergeben werden. Grundsätzlich ist das Feld customFields ein Array aber es kann auch als Objekt angesprochen werden, sofern nur ein kundeneigenes Feld gefüllt werden muss. Bei einem kundeneigenen Feld muss der technische Feldname in camel case angegeben werden, d. h. alles Kleinbuchstaben bis auf Zeichen nach einem Unterstrich; Diese müssen in Großbuchstaben angegeben werden, siehe nachstehendes Beispiel.
Müssen mehr kundeneigene Felder gefüllt werden, müsste der Request wie folgt aussehen.
Änderungszyklus
Bei der Zuordnung eines Änderungszyklus kann entweder dessen ID oder die Beschreibung des Zyklus über das JSON Objekt „cycleInfo“ übergeben werden. Die Eigenschaft „releaseCrmId“ entspricht der ID des Zyklus und „projectTitle“ der Beschreibung des Zyklus.
Wenn Sie einem Objekt einen Zyklus mit ID 8000000211 mit Beschreibung „Release 2022-3“ zuordnen wollen, können Sie entweder die ID oder die Beschreibung mitliefern, sofern die Beschreibung eindeutig ist.
Kurzbeschreibung/Titel des Objekts
Die Kurzbeschreibung bzw. Titel des Objekts, kann über die Eigenschaft „description“ übergeben werden.
Gewünschter Beginn, Gewünschtes Ende, Fälligkeitsdatum
Die Datumsfelder Gewünschter Beginn, Gewünschtes Ende oder das Fälligkeitsdatum können über die Eigenschaften „startDate“, „endDate“ und „dueDate“ übergeben werden. Das Datumsformat entspricht dem Muster YYYY-MM-DD.
Externe ID
Eine Externe ID wie beispielsweise eine Jira Issue ID oder eine ServiceNow Incident ID, kann über die Eigenschaft „externalId“ festgelegt werden.
Multiple Externe IDs
Sofern für bestimmte Vorgangsarten die Zuweisung von mehreren Externen IDs erlaubt ist, kann direkt ein Set aus Externen IDs über die Array-Eigenschaft „externalIds“ übergeben werden.
Auswirkung einer Anforderung, Änderung oder Problems
Die Auswirkung einer Anforderung, Änderung oder Problems, kann über die Eigenschaft „impact“ zugewiesen werden. Zulässige Werte für die Auswirkungen, finden Sie in Tabelle CRMC_SRQM_IMPACT.
Priorität
Die Priorität des Dokuments kann über die Eigenschaft “priority” zugewiesen werden. Zulässige Prioritätswerte können in Tabelle SCPRIO nachgeschlagen werden.
Dringlichkeit
Die Dringlichkeit eines Dokuments wird über die Eigenschaft “urgency” zugewiesen werden. Die Tabelle CRMC_SRQM_URGENC enthält die zulässigen Werte dieses Felds.
Langtext
Der Langtext eines Objekts kann mit der Eigenschaft „longtext“ zugewiesen werden. Da die zugehörige Textart abhängig von der Vorgangsart ist und eventuell kundeneigene Textarten verwendet werden, muss vorab in der Konfiguration des Addons für jede Vorgangsart eine Textart zugwiesen werden, die als Langtext verwendet werden soll, siehe https://galileogroup.atlassian.net/wiki/spaces/CONNECTDOCDE/pages/709558279/REST+API-Konfiguration+REST+API+f+r+den+Solution+Manager#Default-Textobjekte-f%C3%BCr-eine-Gesch%C3%A4ftsvorgangsart .
Weite Textobjekte
Über das Array “texts” können neben dem Langtext weitere Texte über den Webservice übergeben werden. Die benötigten Text IDs müssen Sie vorher im Customizing für das Objekt “CRM_ORDERH” nachschlagen.
Business Partner
Im Vorgang relevanten Business Partner können über die Eigenschaft „partner“ zugewiesen werden. Die Eigenschaft ist dabei ein Array mit Objekten, wobei bei einem Objekt mindestens die Partnerrolle „partnerFct“ und ein Suchtext „partnerLookup“ angegeben werden muss. Der Suchtext funktioniert dabei analog einer Eingabe eines Partners im Web Frontend des Solution Managers und es kann beispielsweise die Nummer oder der Nachname des Partners angegeben werden. Es besteht auch die Möglichkeit kundeneigene Mapping-Regeln für Business Partner zu implementieren.
Beachten Sie bitte, dass die Partnerrolle abhängig von der Vorgangsart ist. Die verfügbaren Partnerrollen für eine Vorgangsart finden Sie in der Tabelle AIC_PARTNER_FCT. Im folgenden Beispiel wird der Rolle „Anforderer“ dem Business Partner 151 zugeordnet und der Rolle „Change Manager“ dem Business Partner 102.
PUT/data/objects/{object_id}
Dieser Endpunkt dient zur Aktualisierung eines Objekts anhand dessen Objekt ID. Welche Werte aktualisiert werden können, finden Sie im vorherigen Kapitel POST /data.
PUT/data/external_ids/{external_id}
Dieser Endpunkt entspricht dem vorherigen mit dem Unterschied, dass das Objekt über dessen Externe ID angesprochen wird. Dieser Endpunkt kann nur verwendet werden, wenn Externe IDs immer eindeutig mit einem Solution Manager Objekt verknüpft ist.
POST /data/objects/{object_id}/action/{action_id}/execute
Dieser Endpunkt kann verwendet werden, um einen Statusübergang eines Objekts auszulösen. Der Pfad-Parameter object_id der Objekt ID des Objekts für die der Statusübergang ausgeführt werden soll und der Pfad-Parameter action_id muss mit dem zugehörigen PPF-Aktionsnamen belegt werden. Eine Liste mit verfügbaren PPF-Aktionen für ein Objekt liefert der Endpunkt GET /data/objects/{object_id}/action.
Kann die Aktion fehlerfrei ausgeführt werden, wird das Objekt zurückgegeben für den die Aktion ausgeführt wurde. Das Schema entspricht hierbei dem Endpunkt GET /data/objects/{object_id}
POST /data/external_ids/{external_id}/action/{action_id}/execute
Dieser Endpunkt arbeitet analog zum vorherigen mit dem Unterschied, dass das Objekt über die Externe ID identifiziert wird.
Endpunkt „Cycles“
Mithilfe des Endpunkts „Cycles“ können Informationen zu Änderungszyklen aus dem Solution Manager abgerufen werden.
GET /cycles
Dieser Endpunkt liefert ein Array mit folgenden Informationen über alle Änderungszyklen im System. Das Rückgabeformat wird noch von einem anderen Endpunkt verwendet, weswegen bei Änderungszyklen identische Werte in unterschiedlichen Feldern zurückgeliefert werden. Die Antwort des Endpunkts enthält folgende Felder.
Name | Typ | Beschreibung |
totalObjects | Wert | Anzahl der gefundenen Änderungszyklen |
objects | Array | Liste mit Details zu den gefunden Änderungszyklen |
Die Objekte aus dem Array „objects“ enthalten dabei folgende Werte.
Name | Typ | Beschreibung |
guid | Wert | Global eindeutige ID |
objectId | Wert | Objekt ID |
processType | Wert | Vorgangsart |
postingDate | Wert | Anlagedatum |
description | Wert | Objektbeschreibung |
userStatus | Wert | Aktueller Status |
userStatusText | Wert | Beschreibung des aktuellen Status |
userStatusFinal | Wert | Kennzeichen („X“ = True, „“ = False), ob der aktuelle Status nicht mehr geändert werden kann. |
configItem | Wert | Wird bei diesem Endpunkt nicht gefüllt! |
configItemText | Wert | Wird bei diesem Endpunkt nicht gefüllt! |
cycleId | Wert | Entspricht der Objekt ID |
cycleText | Wert | Entspricht der Objektbeschreibung |
totalCycleConfigItems | Wert | Anzahl zugeordneter Konfigurationselementen |
cycleConfigItems | Array | Liste zugeordneten Konfigurationselementen |
Die Elemente aus dem Feld „cycleConfigItems“ entsprechen dem folgenden Format:
Name | Typ | Beschreibung |
configItem | Wert | Konfigurationselement |
configItemText | Wert | Konfigurationselementbeschreibung |
Beispiel-Response:
GET /cycles/transaction_types/{transaction_type}
Dieser Endpunkt liefert alle Änderungszyklen, die für eine bestimmte Dokumentenart, z. B. SMCR verwendet werden dürfen. Der Response ist identisch aufgebaut wie der Response des Endpunkts GET /cycles.
Endpunkt „Partner“
Mithilfe des Endpunkts „Partner“ können Informationen zu Geschäftspartnern aus dem Solution Manager abgerufen werden.
GET /data/partner?email={emailAddress)
Dieser Endpunkt liefert Detailinformationen zu einem Geschäftspartner anhand dessen E-Mail Adresse aus dem Solution Manager im Rückgabefeld „partner“.
Name | Typ | Beschreibung |
number | Wert | Geschäftspartnernummer |
guid | Wert | Global eindeutige ID |
firstname | Wert | Vorname |
lastname | Wert | Nachname |
Wert | Email-Adresse | |
validFrom | Wert | Gültig-Von-Datum |
validTo | Wert | Gültig-Bis-Datum |
Beispiel-Response:
Endpunkt „Ping“
Der Endpunkt „Ping“ dient zum Testen von Verbindungen.
GET /ping
Dieser Endpunkt dient im Wesentlichen zum Testen von Verbindungen und liefert folgende Informationen zum gerufenen SAP-Systems zurück und beinhaltet die folgenden Felder.
Name | Typ | Beschreibung |
serverInfo | Objekt | Informationen zum SAP-Server |
systemTime | Wert | Aktuelle Systemzeit |
Das Objekt „serverInfo“ enthält nachstehende Informationen.
Name | Typ | Beschreibung |
name | Wert | Server-Name. |
host | Wert | Name des Host-Servers |
serv | Wert | Service |
msgtypes | Wert | Services des SAP-Servers |
hostadr | Wert | Host IP-Adresse |
servno | Wert | Port-Nummer des Services |
state | Wert | Server-Status |
hostnamelong | Wert | Name des Host-Servers |
hostaddrV4Str | Wert | IPv4 Adresse |
hostaddrV6Str | Wert | IPv6 Adresse |
sysservervice0 | Wert | Registrierte System-Dienste |
sysservervice1 | Wert | Registrierte System-Dienste |
sysservervice2 | Wert | Registrierte System-Dienste |
sysservervice3 | Wert | Registrierte System-Dienste |
Beispiel-Response:
Endpunkt „Tables“
Über diesen Endpunkt können Inhalte von „beliebigen“ SAP-Tabellen angefordert werden. Die Tabellen, dessen Inhalte gelesen werden dürfen, müssen aber vorher über das Konfigurationsprogramm /GAL/SM_API_CONFIG spezifiziert werden.
GET /tables/{table_name}
Dieser Endpunkt ist der Basis-Endpunkt, um Inhalte von SAP-Tabellen zu lösen. Der Endpunkt hat folgende Variationen, um bis zu 4 Filterkriterien angeben zu können. Als Filter-Option wird derzeit nur der Prüfung auf Gleichheit bzw. auf ein Muster unterstützt. Soll eine Muster-Prüfung erfolgen, können die Ersetzungszeichen „*“ und „%“ angegeben werden.
Folgende Endpunkt-Varianten existieren:
/tables/{table_name}/filter/column/{filter_column}/value/{filter_value} |
/tables/{table_name}/filter/column/{filter_column}/value/{filter_value}/column2/{filter_column2}/value2/{filter_value2} |
/tables/{table_name}/filter/column/{filter_column}/value/{filter_value}/column2/{filter_column2}/value2/{filter_value2}/column3/{filter_column3}/value3/{filter_value3} |
/tables/{table_name}/filter/column/{filter_column}/value/{filter_value}/column2/{filter_column2}/value2/{filter_value2}/column3/{filter_column3}/value3/{filter_value3}/column4/{filter_column4}/value4/{filter_value4} |
Wenn die angegebene Tabelle existiert und über den Endpunkt gelesen werden darf, werden enthält die Rückgabe die folgenden zwei Felder.
Name | Typ | Beschreibung |
totalRecords | Wert | Anzahl der gelesenen Datensätze. |
records | Array | Array der gelesenen Datensätze, wobei die Feldnamen den Spaltennamen der Tabelle entsprechen (in Camel Case). |
Beispiel-Response:
Das obige Beispiel liefert die Feldwerte einer Tabelle mit den Spalten MANDT, PRODUCT_ID, CONFIG_ITEM, GXP_CLASS, PROCESS_TEAM und SCR_REVIEWER_DL zurück.