importCubeData
Categorie
| Gegevensverzending |
Omschrijving
| Hiermee worden gegevens in een kubusblad ingevoegd of vervangen. Deze methode kan ook worden gebruikt om gegevens uit een kubusblad te verwijderen door nullen te importeren naar locaties in de kubus. Als u een nul in een kubusblad importeert, worden de gegevens op de locatie van de nul gewist. |
Vereiste machtigingen voor aanroepen
| Importeren |
Vereiste parameters op aanvraag
| Referenties, ImportDataOptions, Versie, Blad, RowData |
De aanvraag van deze methode bevat de parameters die worden gebruikt om te bepalen welk blad en welke versie de opgegeven rijen met gegevens ontvangt. Deze methode kan ook worden gebruikt om gegevens uit een kubusblad te verwijderen door nullen te importeren naar locaties in de kubus. Als u een nul in een kubusblad importeert, worden de gegevens op de locatie van de nul gewist.
Aanvraagindeling
<?xml version='1.0' encoding='UTF-8'?> <call method="importCubeData" 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"/> <version name="Budget 2014" isDefault="false" /> <sheet name="Sales Cube" isUserAssigned="false" /> <rowData> <header>ProductFurniture|CountryRegion|FabricationMachine|Customer|Account|Level|06/2014|07/2014|08/2014|09/2014|01/2015</header> <rows> <row>Coffee table|Argentina|Do-All 15 Vertical|Aeropostale|Price|Corporate Plan|0|0|0|0|0</row> </rows> </rowData> </call>
Elke aanroep van deze API-aanroep moet precies één element van elk van de vermelde typen bevatten:
- referenties
- importDataOptions
- versie
- blad
- rowData
Wanneer de modus is opgegeven als REPLACE, moet bovendien het bereikelement worden opgegeven.
Als het aantal sluistekentekens ( | ) in de kop en de gegevens niet overeenkomen, ontstaat er een fout voor API v30 of hoger.
Voorbeeldaanvraag waarin de vervangingsmodus met bereik wordt opgegeven:
<?xml version='1.0' encoding='UTF-8'?> <call method="importCubeData" callerName="a string that identifies your client application"> <credentials login="sampleuser@company.com" password="my_pwd" instanceCode="INSTANCE1"/> <version name="Budget 2022" isDefault="true" /> <sheet name="Expense Cube" isUserAssigned="false" /> <importDataOptions planOrActuals="Plan" allowParallel="false" moveBPtr="false" mode="REPLACE" /> <!-- Scope parameter specifying the import scope.--> <scope> <!-- Specifies the time scope for import. All values will be specified as time codes.--> <time mode="EXPLICIT"> <timeRange start="01/2021" end="10/2021" /> </time> <!-- Specifies list of accounts in the scope. All values will be specified as code field.--> <accounts mode="EXPLICIT"> <account includeDescendants="true">Op_Expense_Inputs</account> <account includeDescendants="true">Op_Expense_Drivers</account> </accounts> <!-- Specifies list of levels in the scope. All values will be specified as code field.--> <levels mode="INPUT"/> </scope> <rowData> <header>ProductFurniture|CountryRegion|FabricationMachine|Customer|Account|Level|01/2022|02/2022|03/2022|04/2022|05/2022|06/2022|07/2022|08/2022|09/2022|10/2022|11/2022|12/2022</header> <rows> <row>Coffee Table|Argentina|Do-All 15 Vertical|Aeropostale|Units|Development|44567.33|21345.77|22341.43|65567.32|298145.12|12641.83|77821.53|7766342.09|211441.21|88712.43|61940.41|662341.03|775420.25|800345.17</row> </rows> </rowData> </call>
element referenties
| |||
Tagnaam
| referenties | ||
Omschrijving
| Alle API-aanroepen moeten één . bevattenreferenties om de gebruiker te identificeren die de API aanroept. De API-aanroep wordt vervolgens uitgevoerd als deze gebruiker (elk audittrail of geschiedenis van acties in het systeem geeft aan dat deze gebruiker de actie heeft uitgevoerd), en daarom moet de gebruiker over de vereiste machtigingen beschikken om de actie uit te voeren om ervoor te zorgen dat de API-aanroep slagen. | ||
Kenmerken van het element
| |||
Kenmerknaam
| Vereist?
| Waarde
| Voorbeeld
|
aanmelden: | J | De aanmeldingsnaam van de gebruiker die de API-methode aanroept. Deze gebruiker moet over de vereiste machtigingen beschikken om de methode aan te roepen. | sampleuser@company.com |
wachtwoord | J | Het wachtwoord van de gebruiker die de API-methode aanroept. | my_password |
landinstelling | N | Geef de landinstelling op die moet worden gebruikt om inkomende getallen en datums te interpreteren en om uitgaande getallen en datums op te maken (met behulp van het juiste scheidingsteken voor duizendtallen,namen van perioden en datumnotatie). De landinstelling wordt ook gebruikt om de taal op te geven waarin systeemberichten in het antwoord moeten worden weergegeven. Als dit niet is opgegeven, wordt en_US (Amerikaans-Engels) gebruikt. | fr_FR |
instanceCode | N | Als de gebruiker die is opgegeven in de referenties toegang heeft tot meer dan één instance van Adaptive Planning, kan dit kenmerk worden gebruikt om aan te geven dat de gebruiker van plan is toegang te krijgen tot een andere instance dan de standaardinstance. Als dit niet is opgegeven, wordt de standaardinstance van de gebruiker gebruikt. Gebruik de exportInstances-API om de beschikbare instancecodes te bepalen. | MYINSTANCE1 |
Inhoud van het element
| |||
(geen) | |||
importDataOptions element
| |||
Tagnaam
| importDataOptions | ||
Omschrijving
| Hiermee geeft u de opties op die moeten worden gebruikt bij het importeren. | ||
Kenmerken van het element
| |||
Kenmerknaam
| Vereist?
| Waarde
| Voorbeeld
|
planOrActuals | J | Instellen op een van 'plan' of 'Werkelijke waarden' om het type gegevens op te geven dat wordt geïmporteerd. Als deze instelling conflicteert met de versie die is opgegeven in hetVersietag, deDe waarde van de versietag heeft voorrang en deze instelling wordt genegeerd. | Plan |
moveBPtr | N | Alleen gebruikt wanneer deplanOrActuals-kenmerk is ingesteld op:Werkelijke waarden. AlsmoveBPtr is ingesteld optrue, wordt bij het importeren de aanwijzer voor beschikbaarheid van werkelijke waarden in de versie met werkelijke waarden verplaatst naar de laatste periode die in de geïmporteerde gegevens is gevonden. Indien ingesteld op:false, heeft de import geen invloed op welke perioden de werkelijke waarden in een versie weergeven. Dit kenmerk moet worden ingesteld op 'false' als:planOrActuals is ingesteld op:Plannen. | false |
allowParallel | J | Alleen gebruikt wanneer deplanOrActuals-kenmerk is ingesteld op:Werkelijke waarden. Indien ingesteld op:true, wordt de import voortgezet, zelfs als er al een andere import van werkelijke waarden of transacties wordt verwerkt voor deze instance. Indien ingesteld op:false, mislukt de importpoging als er al een import van werkelijke waarden of transacties voor deze instance wordt verwerkt. | false |
useMappings | N | Hiermee geeft u op of importtoewijzingen moeten worden gebruikt voor rekeningen, plannen en dimensiewaarden in de rij-elementen. Overwogenstandaardwaarde true. Alsfalse, moeten de interne ID's worden gebruikt: rekeningen worden geïdentificeerd met een code, niveaus en dimensiewaarden met een naam. | false |
includeContext | N | Hiermee geeft u op of berichten het contextblok mogen bevatten. Waarden zijn:onwaar (nooit context weergeven) oftrue (toon indien van toepassing context). Als dit niet is opgegeven,waar wordt aangenomen. | false |
displayNameIngeschakeld
Alleen beschikbaar in API v30+ voor instances waarvoor de weergavenaam is ingeschakeld. | N | displayNameEnabled=true geeft aan dat importCubeData moet verwachten Account Code , Level Code , Dimension Code , and Dimension Name Column in de payload wanneer Weergavenaam inschakelen is ingeschakeld voor de instance.displayNameEnabled=false geeft aan dat de API importCubeData het API-contract van vóór v30 moet blijven volgen, zelfs als Weergavenaam inschakelen is ingeschakeld voor de instance. De importCubeData-API negeert de eigenschappen van de weergavenaam Account Code , Level Code , Dimension Code , and Dimension Name Column .De standaardwaarde voor displayNameEnabled is onwaar. | false |
modus
Beschikbaar in API v32+ | N | Hiermee geeft u de importmodus op. Dit is APPEND of REPLACE.
APPEND - Bestaande feiten worden bijgewerkt of nieuwe feiten worden ingevoegd. Er worden geen feiten verwijderd. REPLACE: de aanroeper moet een bereikelement opgeven dat de coördinaten vertegenwoordigt van de kubus waarbinnen gegevens worden vervangen door het element in de payload. Alle bestaande gegevens binnen het bereik worden vervangen door de gegevens in de payload van de aanroep. Deze optie wordt ondersteund vanaf API v32-versies en hoger. Het aanroepen van de API met eerdere versies resulteert in een fout. De standaardwaarde voor modus wanneer deze niet is opgegeven, is APPEND. | VERVANGEN |
Inhoud van het element | |||
(geen) | |||
versie-element
| |||
Tagnaam
| versie | ||
Omschrijving
| Hiermee wordt aangegeven welke versie moet worden gebruikt om de aangevraagde gegevens te ontvangen. Voor elke aanroep moet een versie worden opgegeven. | ||
Kenmerken van het element
| |||
Kenmerknaam
| Vereist?
| Waarde
| Voorbeeld
|
naam | N | De naam van de versie die moet worden gebruikt om de gegevens te ontvangen. Er is slechts toegang tot één versie binnen één API-aanroep. Als er geen naam is opgegeven, wordtDe markering isDefault moet zijn ingesteld optrue voor dit element. | Budget 2012 |
isDefault | N | Als de aanroeper toegang wil tot de huidige standaardversie van de instance, ongeacht de naam, kan dit kenmerk worden ingesteld op true. In dat geval wordt het kenmerk name van de tag (indien aanwezig) genegeerd. Als deze waarde onwaar is of als dit kenmerk niet aanwezig is, moet er een versie met de opgegeven naam aanwezig zijn die toegankelijk is voor de gebruiker om deze aanroep te laten slagen. | false |
Inhoud van het element
| |||
(geen) | |||
bladelement
| |||
Tagnaam
| blad | ||
Omschrijving
| Hiermee wordt aangegeven in welk blad de geïmporteerde gegevens moeten worden ontvangen. Elke API-aanroep kan slechts op één bladgegevens worden gericht. | ||
Kenmerken van het element
| |||
Kenmerknaam
| Vereist?
| Waarde
| Voorbeeld
|
naam | J | De naam van het blad waarin de gegevens worden geïmporteerd. | Personeel |
isUserAssigned | N | Hiermee wordt aangegeven dat het blad een aan de gebruiker toegewezen blad is. Als deze niet is opgegeven, wordt deze standaard ingesteld op 'false', wat aangeeft dat het een aan niveaus toegewezen blad is. | false |
Inhoud van het element
| |||
(geen) | |||
bereikelement
| |||
Tagnaam
| Bereik | ||
Omschrijving
| Hiermee geeft u het bereik voor deze import op. Alleen van toepassing wanneer de importmodus is opgegeven als VERVANGEN.
Beschikbaar in API v32+ | ||
Kenmerken van het element
| |||
Kenmerknaam
| Vereist?
| Waarde
| Voorbeeld
|
modus | J | Hiermee geeft u op of celopmerkingen in het bereik moeten worden gewist. Moet een van de drie opgesomde waarden zijn:
Als eraseCellNotes niet is opgegeven, wordt deze standaard ingesteld op GEEN. | GEEN |
Inhoud van het element
| |||
Eén tijdelement, één rekeningelement en één niveau-element, die allemaal verplicht zijn. | |||
tijdselement
| |||
Tagnaam
| Tijd | ||
Omschrijving
| Hiermee worden een of meer tijdsbereikwaarden opgegeven die het tijdsbereik voor de import vertegenwoordigen.
Beschikbaar in API v32+ | ||
Kenmerken van het element
| |||
Kenmerknaam
| Vereist?
| Waarde
| Voorbeeld
|
modus | J | Hiermee geeft u de modus voor het tijdsbereik op. Moet een van de volgende drie opties zijn:
Als de modus is opgegeven en INPUT of VERSION is, mag er geen element timeRange worden opgenomen. Als dit aanwezig is, wordt dit behandeld als een foutvoorwaarde.
Als u VERSIE opgeeft, wordt rekening gehouden met de begindatum van de versie, zelfs als de begindatum van het plan later is dan de begindatum van de versie. | INPUT |
Inhoud van het element
| |||
Een of meer timeRange-elementen, tenzij de modus INPUT of VERSION is. | |||
element timeRange
| |||
Tagnaam
| Tijdbereik | ||
Omschrijving
| Hiermee geeft u één tijdsbereik op voor het tijdsbereik.
Beschikbaar in API v32+ | ||
Kenmerken van het element
| |||
Kenmerknaam
| Vereist?
| Waarde
| Voorbeeld
|
begin | J | De beginperiode voor het importtijdsbereik. | 07/2021 |
end | J | de eindperiode voor het importtijdsbereik. | 08/2021 |
Inhoud van het element
| |||
(geen) | |||
rekeningenelement
| |||
Tagnaam
| rekeningen | ||
Omschrijving
| Hiermee worden de rekeningcodes voor het importbereik opgegeven. Als hier een rekeningcode aanwezig is, maar er geen gegevens voor deze rekening in de importgegevens staan, worden de gegevens in deze rekening verwijderd voor het tijdsbereik en de rest van de bereikcoördinaten.
Beschikbaar in API v32+ | ||
Kenmerken van het element
| |||
Kenmerknaam
| Vereist?
| Waarde
| Voorbeeld
|
modus | J | Hiermee geeft u de modus voor het rekeningbereik op. Moet een van de volgende drie opties zijn:
Als de modus is opgegeven en INPUT of ALL is, mag er geen subelement Rekening worden opgenomen. Als dit aanwezig is, wordt dit behandeld als een fout. | EXPLICIT |
Inhoud van het element
| |||
Een of meer rekeningelementen, tenzij de modus INPUT of ALLE is. | |||
rekeningelement
| |||
Tagnaam
| rekening | ||
Omschrijving
| Hiermee geeft u de rekeningcode op die moet worden opgenomen in het importbereik.
Beschikbaar in API v32+ | ||
Kenmerken van het element
| |||
Kenmerknaam
| Vereist?
| Waarde
| Voorbeeld
|
includeDescendants | N | Als de rekening een rekening op het laagste niveau is, heeft includeDescendants geen effect.
Als de rekening een bovenliggende rekening is, worden alle onderliggende onderliggende rekeningen van deze rekening in het bereik opgenomen als u dit kenmerk opgeeft als waar. Als de rekening een bovenliggende rekening is en includeDescendants is onwaar, wordt dit rekeningelement behandeld alsof het niet is opgegeven. De reden voor deze behandeling van bovenliggende rekeningen is dat een rekening op het laagste niveau soms wordt gepromoveerd tot een bovenliggende rekening en dat de importspecificatie mogelijk niet op tijd wordt bijgewerkt om deze wijziging weer te geven. Als u een bovenliggende rekening negeert met includeDescendants=false, voorkomt u dat gegevens per ongeluk worden verwijderd. Dit is een optioneel kenmerk en de standaardwaarde wordt als onwaar beschouwd. | waar |
Inhoud van het element
| |||
Hiermee geeft u de rekeningcode op van de rekening die wordt gebruikt als onderdeel van het importbereik. Bijvoorbeeld Operational_Expense. | |||
niveaus-element
| |||
Tagnaam
| niveaus | ||
Omschrijving
| Hiermee worden de niveaucodes voor het importbereik opgegeven. Als hier een niveaucode is opgegeven, maar er zijn geen gegevens voor dit niveau in de importgegevens, worden de gegevens in dit niveau verwijderd voor het tijdsbereik en de rest van de bereikcoördinaten.
Beschikbaar in API v32+ | ||
Kenmerken van het element
| |||
Kenmerknaam
| Vereist?
| Waarde
| Voorbeeld
|
modus | J | Hiermee geeft u de modus voor het niveaubereik op. Moet een van de volgende drie opties zijn:
Als de modus is opgegeven en INPUT of ALL is, mag er geen niveausubelement worden opgenomen. Als dit aanwezig is, wordt dit behandeld als een fout. | INPUT |
Inhoud van het element
| |||
Een of meer niveau-elementen, tenzij modus is opgegeven als INPUT of ALL. | |||
niveau-element
| |||
Tagnaam
| niveau | ||
Omschrijving
| Hiermee geeft u de niveaucode op die moet worden opgenomen in het importbereik.
Beschikbaar in API v32+ | ||
Kenmerken van het element
| |||
Kenmerknaam
| Vereist?
| Waarde
| Voorbeeld
|
includeDescendants | N | Als het niveau een bovenliggend niveau is en dit kenmerk als waar opgeeft, worden alle onderliggende niveaus van dit niveau inclusief zichzelf (het enige knooppunt) in het bereik opgenomen.
Dit is een optioneel kenmerk. Als het kenmerk niet wordt opgegeven, is de standaardwaarde onwaar. Als het kenmerk niet is opgegeven of is opgegeven als onwaar en het opgegeven niveau een bovenliggend niveau is, betekent dit dat bij de import rekening wordt gehouden met het knooppunt Alleen (bijvoorbeeld alleen techniek) voor dat niveau voor bereik. Onderliggende niveaus van het niveau worden niet in het bereik opgenomen, tenzij dit expliciet is opgegeven met andere niveau-elementen. | waar |
Inhoud van het element
| |||
Hiermee geeft u de niveaucode van het niveau op als onderdeel van het importbereik. Bijvoorbeeld Ontwikkeling. | |||
rowData-element
| |||
Tagnaam
| rowData | ||
Omschrijving
| Container voor de rijen met gegevens die worden geïmporteerd. | ||
Kenmerken van het element
| |||
(geen) | |||
Inhoud van het element
| |||
Exact éénheader-element en exact éénrows-element. | |||
header-element
| |||
Tagnaam
| kop | ||
Omschrijving
| Hiermee geeft u de namen en volgorde op van de kolommen van de gegevens in de bijbehorenderows-element. | ||
Kenmerken van het element
| |||
(geen) | |||
Inhoud van het element
| |||
Een regel tekst met kolomnamen die met verticale staven zijn gescheiden. Deze kolomnamen moeten overeenkomen met de namen van de dimensies of velden op het blad of met tijdsperiodecodes die gegevens kunnen bevatten. Ze zijn identiek aan de kolomnamen in de importsjabloon voor het blad waarnaar de gegevens worden geïmporteerd, waarbij elke kolomkop van de volgende wordt gescheiden door een verticale balk of een pijpsymbool.
Voor instances waarvoor Weergavenaam is ingeschakeld, biedt de kop geen ondersteuning voor: "<dimension>" in combinatie met "<dimension> Name" of "<dimension> Code" in API v30 of hoger voor door Adaptive Planning ondersteunde landinstellingen. | |||
rows-element
| |||
Tagnaam
| rijen | ||
Omschrijving
| Container voor een of meerrij-elementen. | ||
Kenmerken van het element
| |||
(geen) | |||
Inhoud van het element
| |||
Een of meerrij-elementen. | |||
rij-element
| |||
Tagnaam
| rij | ||
Omschrijving
| Gegevens voor één rij die worden geïmporteerd. | ||
Kenmerken van het element
| |||
(geen) | |||
Inhoud van het element
| |||
Gegevens voor de velden in één rij die worden geïmporteerd, waarbij de waarde van elk veld wordt gescheiden door een verticaal staaf- of pijpsymbool. De gegevensvelden moeten in dezelfde volgorde staan als de regel in het kopelement. Als getallen in de waarden scheidingstekens voor duizendtallen gebruiken, wordt aangenomen dat dit de kommascheidingstekens zijn die worden gebruikt in de landinstelling die is opgegeven in de referenties van de aanvraag. | |||
Antwoordnotatie
Dit zijn voorbeelden van antwoorden op het succesvol en niet succesvol importeren van kubusgegevens.
Voorbeeld van succes
<?xml version='1.0' encoding='UTF-8'?> <response success="true"> <messages> <message key="warning-no-data-imported-dimension-unmapped">Warning: Row 3 was not imported because Coffeee table is unmapped.</message> </messages> </response>
Mislukt (met context)
<?xml version='1.0' encoding='UTF-8'?> <response success="false"> <messages> <message key="err-incomplete-cube-row"> <context> <col header="ProductFurniture" value="Coffee table" /> <col header="CountryRegion" value="" /> <col header="Account" value="Do-All 15 Vertical" /> <col header="Level" value="Aeropostale" /> <col header="06/2014" value="Price" /> <col header="07/2014" value="Corporate Plan" /> <col header="08/2014" value="0.0" /> <col header="09/2014" value="0.0" /> <col header="01/2015" value="0.0" /> </context> Row 1 is missing a value. </message> <message key="err-no-rows">You must import at least one row of data.</message> </messages> </response>
Mislukt (geen context)
<?xml version='1.0' encoding='UTF-8'?> <response success="false"> <messages> <message key="err-incomplete-cube-row">Row 1 is missing a value.</message> <message key="err-no-rows">You must import at least one row of data.</message> </messages> </response>
antwoordelement
| |||
Tagnaam
| antwoord | ||
Kenmerken van het element
| |||
Kenmerknaam
| Vereist?
| Waarde
| Voorbeeld
|
succes | J | Ofwel:waar offalse om aan te geven of de API-aanroep is geslaagd of niet. Zelfs geslaagde aanroepen kunnen waarschuwingsberichten in hun antwoord bevatten. | waar |
Inhoud van het element
| |||
Eén optioneleberichtenelement. | |||
berichtenelement
| |||
Tagnaam
| berichten | ||
Omschrijving
| Container voor een of meerberichtelementen. | ||
Kenmerken van het element
| |||
(geen) | |||
Inhoud van het element
| |||
Een of meerberichtelementen. | |||
berichtelement
| |||
Tagnaam
| bericht | ||
Omschrijving
| Vertegenwoordigt een bericht dat door het systeem wordt teruggestuurd naar de beller. Berichten worden gebruikt voor foutberichten wanneer aanvragen niet slagen, voor waarschuwingsberichten wanneer aanvragen wel slagen en voor bevestigingsberichten na slagen. | ||
Kenmerken van het element
| |||
Kenmerknaam
| Vereist?
| Waarde
| Voorbeeld
|
sleutel | N | Een sleutel is een manier om een bepaald bericht of type bericht te identificeren, wat handig is voor automatische foutregistratie en herstel in clientprogramma's. Sleutels worden niet gewijzigd onder verschillende landinstellingen van aanvragen, zelfs niet als de taal van het bericht verandert. Het is ook onwaarschijnlijk dat sleutels in de toekomst worden gewijzigd als gevolg van aanpassingen in de formulering of terminologie. | invalid-attributevalueid |
Inhoud van het element
| |||
| |||
context element
| |||
Tagnaam
| context | ||
Omschrijving
| Container voor een of meer col-elementen. | ||
Kenmerken van het element
| |||
Kenmerknaam
| Vereist?
| Waarde
| Voorbeeld
|
geen | |||
Inhoud van het element
| |||
Een of meer col-elementen. | |||
col-element
| |||
Tagnaam
| col | ||
Omschrijving
| Vertegenwoordigt de context voor het bericht. Geeft een kop/waarde-paar zodat de rij die het bericht genereert, kan worden geïdentificeerd. | ||
Kenmerken van het element
| |||
Kenmerknaam
| Vereist?
| Waarde
| Voorbeeld
|
kop | J | De kop van de kolom. | 'Account' |
waarde | J | De waarde in de kolom. | "GL-29482-38233" |
Inhoud van het element
| |||
(geen) | |||