importConfigurableModelData
Aktualisiert in API v40 (21. September 2024).
Kategorie
| Datenübermittlung |
Beschreibung
| Fügt Daten in ein modelliertes Tabellenblatt ein, ersetzt oder aktualisiert sie. |
Zum Aufrufen sind Berechtigungen erforderlich
| Importieren |
Auf Anforderung erforderliche Parameter
| Credentials, ImportDataOptions, Version, Sheet, RowData |
Die Anforderung dieser Methode enthält die Parameter, mit denen bestimmt wird, welches Tabellenblatt und welche Version die bereitgestellten Datenzeilen erhält.
Diese Methode kann:
- Neue Zeilen an das Tabellenblatt anhängen.
- Alle Zeilen, die sich aktuell im modellierten Tabellenblatt befinden, werden durch den Import ersetzt.
- Ersetzen Sie alle Daten im Tabellenblatt, aber nur für importierte Ebenen
- Aktualisieren Sie vorhandene Zeilen, indem Sie Zeilen aus dem Import mit einem Importschlüssel abgleichen.
- Aktualisieren Sie vorhandene Zeilen, indem Sie Zeilen aus dem Import mit einem Importschlüssel abgleichen, und fügen Sie neue Zeilen hinzu.
Jeder Aufruf dieses API-Aufrufs muss genau ein Element von jeder der aufgeführten Arten enthalten:
- -Zugangsdaten
- importDataOptions
- Version
- Tabellenblatt
- rowData
Eine Nichtübereinstimmung zwischen der Anzahl der senkrechten Striche (|) im Header und den Daten führt zu einem Fehler bei API v30 oder höher.
Ab API v37 begrenzen wir die maximale Anzahl neuer Zeilen, die Sie in modellierte Tabellenblätter importieren können. Wenden Sie sich an den Support, wenn Sie auf diesen Grenzwert stoßen.
Anforderungsformat
<?xml version='1.0' encoding='UTF-8'?> <call method="importConfigurableModelData" callerName="a string that identifies your client application"> <credentials login="sampleuser@company.com" password="my_pwd" instanceCode="INSTANCE1"/> <importDataOptions planOrActuals="Plan" allowParallel="false" moveBPtr="false" useMappings="false" replaceExisting="2"/> <version name="Budget 2014" isDefault="false" /> <sheet name="Personnel" isUserAssigned="false" /> <rowData> <header>Level|Region|Title|JobCode|Benefits|per|Last Name|First Name|ID|Start|End|Hr/Week|Pay Rate|Pay Rate Display Column</header> <rows> <row>Corporate Plan|Any|CEO|E1|Yes|Yr|Topdog|Andy|1000|12/20/2013|12/30/2014|80|500,000.12|888,888</row> </rows> </rowData> </call>
Anforderungsformat für Aktualisierung vorhandener Zeilen mit importKey
<?xml version='1.0' encoding='UTF-8'?> <call method="importConfigurableModelData" callerName="a string that identifies your client application"> <credentials login="sampleuser@company.com" password="my_pwd"instanceCode="INSTANCE1"/> <importDataOptions planOrActuals="Plan" replaceExisting="3" importKey="Region" allowParallel="false" moveBPtr="false" useMappings="false"/> <version name="Budget 2014" isDefault="false" /> <sheet name="Personnel" isUserAssigned="false" /> <rowData> <header>Plan|Region|Benefits|per</header> <rows> <row>Europe Sales|W-US|Yes|Hr</row> </rows> </rowData> </call>
Element „Zugangsdaten“.
Tag-Name
| -Zugangsdaten | ||
Beschreibung
| Alle API-Aufrufe müssen eine einzelne enthaltenElement credentials, um den Benutzer zu identifizieren, der die API aufruft. Der API-Aufruf wird dann als dieser Benutzer ausgeführt (jeder Audit-Trail oder jede Aktionshistorie im System zeigt, dass dieser Benutzer die Aktion ausgeführt hat). Daher muss der Benutzer über die erforderlichen Berechtigungen zum Ausführen der Aktion verfügen, damit der API-Aufruf ausgeführt werden kann erfolgreich ist. | ||
Attribute des Elements
| |||
Name des Attributs
| erforderlich?
| Wert
| Beispiel
|
anmelden | J | Der Anmeldename des Benutzers, der die API-Methode aufruft. Dieser Benutzer muss über die erforderlichen Berechtigungen zum Aufrufen der Methode verfügen. | sampleuser@company.com |
Kennwort | J | Das Kennwort des Benutzers, der die API-Methode aufruft. | my_password |
Gebietsschema | N | Geben Sie das Gebietsschema an, das verwendet werden soll, um eingehende Zahlen und Datumsangaben zu interpretieren und ausgehende Zahlen und Datumsangaben zu formatieren (mit dem entsprechenden Tausendertrennzeichen, den entsprechenden Zeitperiodennamen und der entsprechenden Datumsformatierung). Das Gebietsschema wird auch verwendet, um die Sprache anzugeben, in der Systemmeldungen in der Antwort angezeigt werden sollen. Wenn nicht angegeben, wird en_US (amerikanisches Englisch) verwendet. | fr_FR |
instanceCode | N | Wenn der in den Zugangsdaten angegebene Benutzer Zugriff auf mehr als eine Instanz von hat, Adaptive Planning : Dieses Attribut kann verwendet werden, um anzugeben, dass der Benutzer auf eine andere Instanz als seine Standardinstanz zugreifen möchte. Wenn nicht angegeben, wird die Standardinstanz des Benutzers verwendet. Verwenden Sie die exportInstances-API, um die verfügbaren Instanzcodes zu ermitteln. | MYINSTANCE1 |
Inhalt des Elements
| |||
(Keine) | |||
importDataOptions element
| |||
Tag-Name
| importDataOptions | ||
Beschreibung
| Gibt die Optionen an, die beim Ausführen des Imports verwendet werden sollen. | ||
Attribute des Elements
| |||
Name des Attributs
| erforderlich?
| Wert
| Beispiel
|
planOrActuals | J | Auf eines von setzenPlan-bzwIstzahlen, um die Art der zu importierenden Daten anzugeben. Wenn diese Einstellung in Konflikt mit der im Tag "Version" angegebenen steht, hat der Wert des Tags "Version" Vorrang und diese Einstellung wird ignoriert. | Plan |
moveBPtr | N | Wird nur verwendet, wenn die zu importierenden Daten einen Satz von Zeitspannenzahlen in jeder Zeile haben. WennmoveBPtr ist auf gesetztwahr ist, verschiebt der Import den Istzahlen-Verfügbarkeitszeiger in der Istzahlen-Version in die letzte Zeitperiode, die in den importierten Daten gefunden wurde. Wenn aktiviertfalsch: Der Import hat keine Auswirkungen darauf, welche Zeitperioden in welcher Version Istzahlen anzeigen. Dieses Attribut muss auf "false" gesetzt werden, wenn planOrActuals auf "Plan" gesetzt ist. | false |
allowParallel | J | Wenn aktiviertwahr, dann wird ein Import fortgesetzt, auch wenn für diese Instanz bereits ein anderer Istzahlen- oder Transaktionsimport in Bearbeitung ist. Wenn aktiviertfalsch: Ein Importversuch schlägt fehl, wenn für diese Instanz bereits ein Istzahlen- oder Transaktionsimport verarbeitet wird. | false |
useMappings | N | Gibt an, ob Import-Mappings für Konten, Pläne und Dimensionswerte innerhalb der Zeilenelemente verwendet werden sollen. Kommt in Fragestandardmäßig „true“ Wennfalse, dann sollten die internen IDs verwendet werden: Konten werden anhand von Code, Ebenen und Dimensionswerte anhand des Namens identifiziert. | false |
replaceExisting | N | Auf "1" oder "Wahr" setzen, um alle vorhandenen Zeilen in allen Ebenen durch die neuen Zeilen zu ersetzen, die importiert werden (d. h. alle zuvor vorhandenen Zeilen in allen Ebenen löschen). Nur Benutzer mit der Berechtigung In alle Speicherorte importieren können diese Option verwenden.Auf „0“ oder „false“ setzen, um die importierten Zeilen an die vorhandenen Zeilen anzuhängen, auch wenn die neuen Zeilen Duplikate sind. Setzen Sie diesen Wert auf „2“, um die vorhandenen Zeilen im modellierten Tabellenblatt durch die neuen Zeilen zu ersetzen, die importiert werden, jedoch nur für Zeilen mit übereinstimmender Ebene und gesicherten Dimensionen. Für Zeilen mit Kombinationen von Ebenen und gesicherten Dimensionen, die in der hochgeladenen Tabelle keine nicht gesplitteten Zeilen enthalten, werden die vorhandenen Zeilen nicht entfernt, es sei denn, die Zeile war ein Split einer Zeile, die durch den Upload ersetzt wird. ersetzenVorhandene prüft die verwendeten Dimensionen und prüft, ob Daten in derselben Ebene, demselben Konto, derselben Zeitperiode und derselben Version vorhanden sind. Wenn ein Zeilenschlüssel vorhanden ist, werden auch die Spalten des Zeilenschlüssels abgeglichen. Wenn sich Daten am selben Speicherort im System befinden, werden sie durch den Import ersetzt. Diese Ersetzung erfolgt zeilenweise. Beim Import wird nicht alles auf einmal ersetzt. Nicht übereinstimmende Importzeilen werden an das Tabellenblatt angehängt. Beispiel: Sie führen zwei Importe aus. Ihre erste Importdatei lädt Daten, die Ihre zweite Importdatei nicht enthält. Diese vorhandenen Daten bleiben nach dem zweiten Import erhalten. Wenn Sie alle Daten in einer bestimmten Spalte löschen möchten, schließen Sie die Spalte ein, aber lassen Sie die Spaltenwerte leer. Spaltenwerte für nicht erwähnte Spalten bleiben unverändert. Setzen Sie diesen Wert auf „3“, um vorhandene Zeilen im modellierten Tabellenblatt entsprechend den neuen importierten Zeilen zu aktualisieren. Eine Warnung wird zurückgegeben, wenn eine Zeile nicht mit einer vorhandenen Zeile übereinstimmt. Für diesen Modus ist ein importKey erforderlich. Tabellenblätter, für die Splits zulassen
Setzen Sie diesen Wert auf „4“, um vorhandene Zeilen im modellierten Tabellenblatt zu aktualisieren, damit sie die neuen Zeilen wiedergeben, die importiert werden, und um neue Zeilen für alle Zeilen einzufügen, die nicht mit einer vorhandenen Zeile übereinstimmen. Für diesen Modus ist ein importKey erforderlich. Die einzigen erforderlichen Spalten sind "Importschlüssel", "Ebene" und alle Textauswahlen, auch wenn keine neuen Zeilen hinzugefügt werden. Tabellenblätter, für die Splits zulassen
Setzen Sie diesen Wert auf 5, um vorhandene Zeilen basierend auf dem Bereich zu ersetzen, der aktuell nur Eingabeebenen für die Funktion „Nur durch Ebene ersetzen“ unterstützt. Der Bereich wird mithilfe eines neuen Bereichselements angegeben. Nur die Zeilen, die mit dem angegebenen Bereich übereinstimmen, werden beim Import durch die Nutzlast ersetzt. Zeilen, die nicht mit dem Bereich übereinstimmen, sind davon nicht betroffen. Der Standardwert ist „true“. | wahr |
importKey | N | Der Spaltenname des modellierten Tabellenblatts, der beim Aktualisieren von Zeilen in modellierten Tabellenblättern als Importschlüssel verwendet werden soll. Adaptive Planning verwendet die Importschlüsselspalte, um jede Zeile im Import mit Zeilen im modellierten Tabellenblatt abzugleichen. Der Importschlüsselwert jeder Zeile muss eindeutig sein.Dieses Attribut kann nur verwendet werden, wenn ersetzenExisting "3" oder "4" ist. Importschlüsselspalten können eine der folgenden sein:
| Ebene |
includeContext | N | Gibt an, ob Nachrichten den Kontextblock enthalten können. Werte sindfalsch (Kontext nie anzeigen) oderwahr (gegebenenfalls Kontext anzeigen). Falls nicht angegeben„true“ wird angenommen. | false |
displayNameEnabled
Nur in API v31 und höher für Instanzen verfügbar, die den Anzeigenamen aktivieren. | N | displayNameEnabled=true gibt an, dass die API die Spalten "Kontocode", "Ebenencode", "Dimensionscode" und "Dimensionsname" in der Nutzlast erwarten soll, wenn für die Instanz die Einstellung "Anzeigenamen aktivieren" auf EIN gesetzt ist. displayNameEnabled=false gibt an, dass die API weiterhin den API-Vertrag vor v30 befolgen soll, auch wenn für die Instanz die Einstellung "Anzeigename aktivieren" auf EIN gesetzt ist. Der Standardwert für displayNameEnabled ist "false". | false |
applyValidationRules
Nur in API v38 + verfügbar. | N | ApplyValidationRules = true gibt an, dass die API Regelvalidierungen für modellierte Tabellenblätter für alle importierten Daten durchführt, wenn die API-Version größer als gleich v38 ist.
ApplyValidationRules = false gibt an, dass die API Regelvalidierungen für modellierte Tabellenblätter für alle importierten Daten ignoriert. Der Standardwert für ApplyValidationRules ist "true". | false |
Inhalt des Elements
| |||
(Keine) | |||
-Versionselement
| |||
Tag-Name
| Version | ||
Beschreibung
| Gibt an, welche Version zum Empfangen der angeforderten Daten verwendet werden soll. Für jeden Aufruf muss eine Version angegeben werden. | ||
Attribute des Elements
| |||
Name des Attributs
| erforderlich?
| Wert
| Beispiel
|
Namen | N | Der Name der Version, die zum Empfangen der Daten verwendet werden soll. Mit einem einzigen API-Aufruf kann nur auf eine Version zugegriffen werden. Wenn kein Name angegeben wird, geschieht diesDas Kennzeichen isDefault muss auf gesetzt werdenwahr für dieses Element. | Budget 2014 |
isDefault | N | Wenn der Aufrufer unabhängig von ihrem Namen auf die aktuelle Standardversion der Instanz zugreifen möchte, kann dieses Attribut auf „true“ gesetzt werden. In diesem Fall wird das Attribut „name“ des Tags (falls vorhanden) ignoriert. Andernfalls, wenn dieser Wert falsch ist oder dieses Attribut nicht vorhanden ist, muss eine Version mit dem angegebenen Namen vorhanden und für den Benutzer zugänglich sein, damit dieser Aufruf erfolgreich ist. | false |
Inhalt des Elements
| |||
(Keine) | |||
Tabellenblattelement
| |||
Tag-Name
| Tabellenblatt | ||
Beschreibung
| Gibt an, welches Tabellenblatt die importierten Daten erhalten soll. Jeder API-Aufruf kann nur auf die Daten eines Tabellenblatts abzielen. | ||
Attribute des Elements
| |||
Name des Attributs
| erforderlich?
| Wert
| Beispiel
|
Namen | J | Der Name des Tabellenblatts, in das die Daten importiert werden. | Personal |
isUserAssigned | N | Gibt an, dass das Tabellenblatt ein Tabellenblatt mit Benutzerzuweisung ist. Wenn nicht angegeben, wird der Standardwert „false“ lautet, was angibt, dass es sich um ein Tabellenblatt mit Ebenenzuweisung handelt. | false |
Inhalt des Elements
| |||
(Keine) | |||
Element „Scope“.
| |||
Tag-Name
| Bereich (verfügbar mit API v40) | ||
Beschreibung
| Gibt den Bereich für diesen Import an. Beispiel:
Nur zulässig, wenn das Attribut ersetzenExisting des Elements importDataOptions 5 ist. | ||
rowData element
| |||
Tag-Name
| rowData | ||
Beschreibung
| Container für die zu importierenden Datenzeilen. | ||
Attribute des Elements
| |||
(Keine) | |||
Inhalt des Elements
| |||
Genau eineHeader-Element und genau einsZeilenelement | |||
Header-Element
| |||
Tag-Name
| -Header | ||
Beschreibung
| Gibt die Namen und die Reihenfolge der Spalten der Daten in der entsprechenden anZeilenelement | ||
Attribute des Elements
| |||
(Keine) | |||
Inhalt des Elements
| |||
Eine Textzeile mit durch vertikale Balken getrennten Spaltennamen. Diese Spaltennamen müssen mit den Namen der Dimensionen oder Felder im Tabellenblatt oder mit den Codes der Zeitperioden übereinstimmen, die Daten enthalten können. Sie sind identisch mit den Spaltennamen in der Importvorlage für das Tabellenblatt, in das die Daten importiert werden, wobei jeder Spalten-Header durch einen vertikalen Balken oder einen senkrechten Strich | vom nächsten getrennt ist .
Bei Instanzen, die Anzeigename aktivieren, wird der Header nicht unterstützt "<dimension>" in Kombination mit "<dimension> Name" oder "<dimension> Code" in API v30 oder höher für von Adaptive Planning unterstützte Gebietsschemas. | |||
Zeilenelement
| |||
Tag-Name
| Zeilen | ||
Beschreibung
| Container für einen oder mehrereZeilenelementen. | ||
Attribute des Elements
| |||
(Keine) | |||
Inhalt des Elements
| |||
Einen oder mehrereZeilenelementen. | |||
Zeilenelement
| |||
Tag-Name
| Zeile | ||
Beschreibung
| Daten für eine einzelne Zeile, die importiert wird. | ||
Attribute des Elements
| |||
(Keine) | |||
Inhalt des Elements
| |||
Daten für die Felder in einer einzelnen Zeile, die importiert werden, wobei der Wert jedes Felds durch einen vertikalen Balken oder einen senkrechten Strich getrennt ist. Die Datenfelder müssen in derselben Reihenfolge sein wie die Zeile im Header-Element. Wenn Zahlen in den Werten Tausendertrennzeichen verwenden, werden diese als Kommastrennzeichen im Gebietsschema verwendet, das in den Zugangsdaten der Anforderung angegeben wurde. | |||
Antwortformat
Dies sind Beispiele für Antworten nach erfolgreichem und nicht erfolgreichem Import von Daten.
Erfolgreiches Beispiel
<?xml version='1.0' encoding='UTF-8'?> <response success="true"> <messages> <message key="modeled-import-success">Personnel import successful. Rows imported: 1</message> <message key="modeled-import-replace">All existing rows were replaced.</message> </messages> </response>
Fehlgeschlagen (mit Kontext)
<?xml version='1.0' encoding='UTF-8'?> <response success="false"> <messages> <message key="modeled-import-failed">The Personnel import has failed.</message> <message key="error-import">Import Failed with the following error: 1 Error(s) Occurred.</message> <message key="import-detail">Additional information:</message> <message key="warning-nonexistent-dimension-value">Warning: No data was imported for rows with the following dimension values because the dimension values for Plan do not exist: Development1.</message> <message key="invalid-plan-choice-withCoordinate"> <context> <col header="Plan" value="Development1" /> <col header="Region" value="C-US" /> <col header="Title" value="CEO" /> <col header="JobCode" value="E1" /> <col header="Benefits" value="Yes" /> <col header="per" value="Yr" /> <col header="Last Name" value="Topdog" /> <col header="First Name" value="Andy" /> <col header="ID" value="1000" /> <col header="Start" value="12/20/2013" /> <col header="End" value="12/30/2014" /> <col header="Hr/Week" value="80.0" /> <col header="Pay Rate" value="500000.12" /> <col header="Pay Rate Display Column" value="888,888" /> </context> Invalid Level Choice: Development1 on row 1 column A </message> </messages> </response>
Fehlgeschlagen (kein Kontext)
<?xml version='1.0' encoding='UTF-8'?> <response success="false"> <messages> <message key="modeled-import-failed">The Personnel import has failed.</message> <message key="error-import">Import Failed with the following error: 1 Error(s) Occurred.</message> <message key="import-detail">Additional information:</message> <message key="warning-nonexistent-dimension-value">Warning: No data was imported for rows with the following dimension values because the dimension values for Plan do not exist: Development1.</message> <message key="invalid-plan-choice-withCoordinate">Invalid Level Choice: Development1 on row 1 column A</message> </messages> </response>
Antwortelement
| |||
Tag-Name
| -Antwort | ||
Attribute des Elements
| |||
Name des Attributs
| erforderlich?
| Wert
| Beispiel
|
Erfolg haben | J | Beideswahr oderfalsch: Gibt an, ob der API-Aufruf erfolgreich war oder nicht. Selbst erfolgreiche Aufrufe können in ihrer Antwort Warnmeldungen enthalten. | true |
Inhalt des Elements
| |||
Einzelne optionaleNachrichtenelement | |||
Nachrichtenelement
| |||
Tag-Name
| -Nachrichten | ||
Beschreibung
| Container für einen oder mehrere-Nachrichtenelemente. | ||
Attribute des Elements
| |||
(Keine) | |||
Inhalt des Elements
| |||
Einen oder mehrere-Nachrichtenelemente. | |||
Nachrichtenelement
| |||
Tag-Name
| Nachricht | ||
Beschreibung
| Stellt eine Nachricht dar, die vom System an den Aufrufer zurückgesendet wird. Nachrichten werden für Fehlermeldungen verwendet, wenn Anforderungen nicht erfolgreich sind, als Warnmeldungen, wenn Anforderungen erfolgreich sind, und als Bestätigungsmeldungen bei Erfolgreich. | ||
Attribute des Elements
| |||
Name des Attributs
| erforderlich?
| Wert
| Beispiel
|
-Schlüssel | N | Wenn ein Schlüssel angegeben wird, kann eine bestimmte Meldung oder eine bestimmte Meldungsart identifiziert werden. Dies ist für eine automatische Fehlerprotokollierung und Wiederherstellung in Client-Programmen hilfreich. Schlüssel ändern sich nicht unter verschiedenen Gebietsschemas von Anforderungen, auch wenn sich die Sprache der Nachricht ändert. Es ist auch fehlgeschlagen, dass sich Schlüssel in Zukunft aufgrund von Wording-Anpassungen oder Änderungen der Terminologie ändern. | invalid-attributevalueid |
Inhalt des Elements
| |||
| |||
-Kontextelement
| |||
Tag-Name
| context | ||
Beschreibung
| Container für ein oder mehrere Spaltenelemente. | ||
Attribute des Elements
| |||
Name des Attributs
| erforderlich?
| Wert
| Beispiel
|
Keine | |||
Inhalt des Elements
| |||
Ein oder mehrere Spaltenelemente | |||
Element col
| |||
Tag-Name
| col | ||
Beschreibung
| Stellt den Kontext für die Nachricht dar. Gibt ein Header/Wert-Paar an, damit die Zeile identifiziert werden kann, die die Meldung generiert. | ||
Attribute des Elements
| |||
Name des Attributs
| erforderlich?
| Wert
| Beispiel
|
-Header | J | Der Header der Spalte. | "Konto" |
Wert | J | Der Wert in der Spalte. | "GL-29482-38233" |
Inhalt des Elements
| |||
(Keine) | |||