importConfigurableModelData
Aggiornato nell'API v40 (21 settembre 2024).
Categoria | Inoltro dei dati |
Descrizione | Inserisce, sostituisce o aggiorna i dati in un foglio modellato. |
Autorizzazioni necessarie per richiamare | Importazione |
Parametri obbligatori su richiesta | Credentials, ImportDataOptions, Version, Sheet, RowData |
La richiesta di questo metodo contiene i parametri che verranno utilizzati per determinare quale foglio e quale versione riceveranno le righe di dati fornite.
Questo metodo può:
- Aggiungere nuove righe al foglio.
- Sostituire tutte le righe attualmente presenti nel foglio modellato con l'importazione.
- Sostituisci tutti i dati nel foglio, ma solo per i livelli importati
- Aggiornare le righe esistenti facendo corrispondere le righe dell'importazione con una chiave di importazione.
- Aggiornare le righe esistenti abbinando le righe dell'importazione con una chiave di importazione e aggiungere nuove righe.
Ogni chiamata di questa chiamata API deve contenere esattamente un elemento di ciascuno dei tipi elencati:
- credenziali
- importDataOptions
- versione
- foglio
- rowData
Una mancata corrispondenza tra il numero di caratteri pipe ( | ) nell'intestazione e i dati causerà un errore per l'API v30 o successiva.
A partire dall'API v37, il numero massimo di nuove righe che è possibile importare nei fogli modellati è limitato. Contattare l'assistenza se si incontra questo limite.
Formato richiesta
<?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>
Formato richiesta per aggiornamento righe esistenti con 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>
elemento credenziali
Nome tag | credenziali | ||
Descrizione | Tutte le chiamate API devono contenere una singola chiamatacredenziali per identificare l'utente che richiama l'API. La chiamata API viene quindi eseguita come utente (qualsiasi audit trail o storico delle azioni nel sistema mostrerà che l'azione è stata eseguita dall'utente) e pertanto l'utente deve disporre delle autorizzazioni necessarie per eseguire l'azione affinché la chiamata API avere esito positivo. | ||
Attributi dell'elemento | |||
Nome attributo | Obbligatorio? | Valore | Esempio |
login | S | Il nome di accesso dell'utente che richiama il metodo API. L'utente deve disporre delle autorizzazioni necessarie per richiamare il metodo. | sampleuser@company.com |
password | S | La password dell'utente che richiama il metodo API. | my_password |
impostazioni internazionali | N | Specificare le impostazioni internazionali da utilizzare per interpretare i numeri e le date in entrata e per formattare i numeri e le date in uscita (utilizzando il separatore delle migliaia, i nomi dei periodi di tempo e la formattazione della data appropriati). Le impostazioni internazionali vengono utilizzate anche per specificare la lingua in cui devono essere visualizzati i messaggi di sistema nella risposta. Se non viene specificato, viene utilizzato en_US (inglese americano). | fr_FR |
instanceCode | N | Se l'utente specificato nelle credenziali ha accesso a più istanze di Adaptive Planning , questo attributo può essere utilizzato per specificare che l'utente intende accedere a un'istanza diversa da quella predefinita. Se non viene specificata, verrà utilizzata l'istanza predefinita dell'utente. Per determinare i codici di istanza disponibili, utilizzare l'API exportInstances. | MYINSTANCE1 |
Contenuto dell'elemento | |||
(nessuno) | |||
elemento importDataOptions | |||
Nome tag | importDataOptions | ||
Descrizione | Specifica le opzioni da utilizzare quando si esegue l'importazione. | ||
Attributi dell'elemento | |||
Nome attributo | Obbligatorio? | Valore | Esempio |
planOrActuals | S | Impostare su uno diPiano oImporti effettivi per specificare il tipo di dati da importare. Se questa impostazione è in conflitto con la versione specificata nel tag Version, il valore del tag Version ha la precedenza e l'impostazione viene ignorata. | Piano |
moveBPtr | N | Utilizzato solo quando i dati da importare hanno un insieme di numeri di intervallo di tempo per ogni riga. SemoveBPtr è impostato sutrue, l'importazione sposterà il puntatore di disponibilità degli importi effettivi nella versione importi effettivi in modo che sia l'ultimo periodo di tempo trovato nei dati importati. Se impostato sufalse, l'importazione non influirà sui periodi di tempo che mostrano gli importi effettivi in nessuna versione. Questo attributo deve essere impostato su false se planOrActuals è impostato su Plan. | false |
allowParallel | S | Se impostato sutrue, l'importazione procederà anche se è già in corso un'altra importazione di importi effettivi o transazioni per questa istanza. Se impostato sufalse, un tentativo di importazione avrà esito negativo se è già in corso un'importazione di importi effettivi o transazioni per questa istanza. | falso |
useMappings | N | Specifica se utilizzare le mappature di importazione per conti, piani e valori dimensione all'interno degli elementi riga. Consideratovero per impostazione predefinita. Sefalse, devono essere utilizzati gli ID interni: i conti sono identificati da codice, livelli e valori dimensione in base al nome. | falso |
replaceExisting | N | Impostare su "1" o "true" per sostituire tutte le righe esistenti a tutti i livelli con le nuove righe importate (ovvero, cancellare tutte le righe esistenti in precedenza a tutti i livelli). Solo gli utenti con l'autorizzazione Importa in tutte le sedi possono utilizzare questa opzione.Impostare su "0" o "false" per aggiungere le righe importate alle righe esistenti, anche se le nuove righe sono duplicate. Impostare su "2" per sostituire le righe esistenti nel foglio modellato con le nuove righe importate, ma solo per le righe con livello corrispondente e dimensioni associate. Le righe delle combinazioni di dimensioni e di livello associate che non contengono righe non suddivise nel foglio di calcolo caricato non verranno rimosse dalle righe esistenti, a meno che la riga non sia una suddivisione di una riga che viene sostituita dal caricamento. replaceExisting esamina le dimensioni utilizzate e se i dati sono presenti nello stesso livello, conto, periodo di tempo e versione. Se esiste una chiave di riga, viene eseguita una corrispondenza anche con la colonna o le colonne della chiave di riga. Se nel sistema sono presenti dati nella stessa posizione, l'importazione li sostituisce. La sostituzione avviene riga per riga. L'importazione non sostituisce tutto all'istante. Le righe di importazione non abbinate vengono aggiunte al foglio. Ad esempio, si eseguono due importazioni. il primo file di importazione carica i dati che il secondo file di importazione non contiene. I dati esistenti rimarranno dopo la seconda importazione. Se si desidera eliminare tutti i dati in una determinata colonna, includere la colonna ma lasciare vuoti i valori della colonna. I valori delle colonne per le colonne non menzionate rimangono invariati. Impostare su "3" per aggiornare le righe esistenti nel foglio modellato in modo che riflettano le nuove righe importate. Se una riga non corrisponde a una riga esistente, verrà restituito un avviso. Questa modalità richiede un importKey. I fogli con le suddivisioni Consenti Impostare su "4" per aggiornare le righe esistenti nel foglio modellato in modo che riflettano le nuove righe importate e inserire nuove righe per quelle che non corrispondono a una riga esistente. Questa modalità richiede un importKey. Le uniche colonne obbligatorie sono Chiave di importazione, Livello ed eventuali selettori di testo, anche quando non si aggiungono nuove righe. I fogli con le suddivisioni Consenti Impostare su 5 per sostituire le righe esistenti in base all'ambito che attualmente supporta solo i livelli di input per la funzionalità di sostituzione solo per livello. L'ambito viene fornito utilizzando un nuovo elemento di ambito. Solo le righe che corrispondono all'ambito specificato verranno sostituite dal payload nell'importazione. Le righe che non corrispondono all'ambito rimarranno invariate. Il valore predefinito è vero. | true |
importKey | N | Il nome della colonna del foglio modellato da utilizzare come chiave di importazione quando si aggiornano le righe del foglio modellato. Adaptive Planning utilizza la colonna chiave di importazione per abbinare ogni riga dell'importazione alle righe del foglio modellato. Il valore della chiave di importazione di ogni riga deve essere univoco.Questo attributo può essere utilizzato solo quando replaceExisting è "3" o "4". Le colonne chiave di importazione possono essere una delle seguenti:
| Level |
includeContext | N | Specifica se i messaggi possono includere il blocco di contesto. I valori sonofalse (non mostrare mai il contesto) otrue (mostrare il contesto, se appropriato). Se non specificato,si presuppone vero. | falso |
displayNameEnabled
Disponibile solo nell'API v31+ per le istanze che abilitano il nome visualizzato. | N | displayNameEnabled=true indica che l'API deve prevedere le colonne Codice conto, Codice livello, Codice dimensione e Nome dimensione nel payload quando l'impostazione Abilita nome visualizzato è attiva per l'istanza. displayNameEnabled=false indica che l'API deve continuare a seguire il contratto API precedente alla v30 anche quando l'impostazione Abilita nome visualizzato è attiva per l'istanza. Il valore predefinito per displayNameEnabled è "false". | falso |
applyValidationRules
Disponibile solo nell'API v38 +. | N | applyValidationRules=true indica che l'API eseguirà le convalide delle regole del foglio modellato per tutti i dati importati quando la versione dell'API è superiore a v38.
applyValidationRules=false indica che l'API ignorerà le convalide delle regole del foglio modellato per tutti i dati importati. Il valore predefinito per applyValidationRules è "true". | falso |
Contenuto dell'elemento | |||
(nessuno) | |||
elemento versione | |||
Nome tag | versione | ||
Descrizione | Indica la versione da utilizzare per ricevere i dati richiesti. È necessario specificare una versione per ogni chiamata. | ||
Attributi dell'elemento | |||
Nome attributo | Obbligatorio? | Valore | Esempio |
nome | N | Il nome della versione da utilizzare per ricevere i dati. È possibile accedere a una sola versione all'interno di una singola chiamata API. Se non viene specificato un nome, il fileIl flag isDefault deve essere impostato sutrue per questo elemento. | Budget 2014 |
isDefault | N | Se il chiamante desidera accedere alla versione predefinita corrente dell'istanza indipendentemente dal nome, questo attributo può essere impostato su true, nel qual caso l'attributo name del tag (se presente) viene ignorato. In caso contrario, se questo valore è false o se questo attributo non è presente, affinché la chiamata abbia esito positivo deve esistere ed essere accessibile all'utente. | falso |
Contenuto dell'elemento | |||
(nessuno) | |||
elemento del foglio | |||
Nome tag | foglio | ||
Descrizione | Indica il foglio che deve ricevere i dati importati. Ogni chiamata API può avere come destinazione solo i dati di un foglio. | ||
Attributi dell'elemento | |||
Nome attributo | Obbligatorio? | Valore | Esempio |
nome | S | Il nome del foglio in cui verranno importati i dati. | Personale |
isUserAssigned | N | Indica che il foglio è un foglio assegnato da un utente. Se non viene specificato, il valore predefinito è false, a indicare che si tratta di un foglio assegnato a livello. | falso |
Contenuto dell'elemento | |||
(nessuno) | |||
Elemento ambito | |||
Nome tag | Ambito (disponibile con API v40) | ||
Descrizione | Specifica l'ambito dell'importazione. Esempio:
Consentito solo quando l'attributo replaceExisting dell'elemento importDataOptions è 5. | ||
elemento rowData | |||
Nome tag | rowData | ||
Descrizione | Contenitore per le righe di dati da importare. | ||
Attributi dell'elemento | |||
(nessuno) | |||
Contenuto dell'elemento | |||
Esattamente unoelemento di intestazione ed esattamente unoelemento righe | |||
elemento di intestazione | |||
Nome tag | intestazione | ||
Descrizione | Specifica i nomi e l'ordine delle colonne dei dati nel corrispondenteelemento righe | ||
Attributi dell'elemento | |||
(nessuno) | |||
Contenuto dell'elemento | |||
Una riga di testo con nomi di colonna separati da barre verticali. Questi nomi di colonna devono corrispondere ai nomi delle dimensioni o dei campi del foglio o ai codici dei periodi di tempo che possono contenere dati. Sono identici ai nomi delle colonne presenti nel Modello di importazione per il foglio in cui vengono importati i dati, con ogni intestazione di colonna separata dalla successiva da una barra verticale o da un simbolo di barra verticale | .
Per le istanze che abilitano il Nome visualizzato, l'intestazione non è supportata "<dimension>" in combinazione con "<dimension> Name" o "<dimension> Code" in API v30 o versioni successive per le impostazioni internazionali supportate da Adaptive Planning. | |||
elemento righe | |||
Nome tag | righe | ||
Descrizione | Contenitore per uno o piùelementi riga | ||
Attributi dell'elemento | |||
(nessuno) | |||
Contenuto dell'elemento | |||
Uno o piùelementi riga | |||
elemento riga | |||
Nome tag | riga | ||
Descrizione | Dati per una singola riga in fase di importazione. | ||
Attributi dell'elemento | |||
(nessuno) | |||
Contenuto dell'elemento | |||
I dati dei campi di una singola riga in fase di importazione, il valore di ogni campo separato da una barra verticale o da un simbolo di barra verticale. I campi di dati devono essere nello stesso ordine della riga nell'elemento di intestazione. Se i numeri nei valori utilizzano separatori di migliaia, si presume che siano i separatori di virgole utilizzati nelle impostazioni internazionali specificate nelle credenziali della richiesta. | |||
Formato risposta
Questi sono esempi di risposte per l'importazione di dati riuscita e non riuscita.
Esempio di successo
<?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>
Non riuscito (con contesto)
<?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>
Non riuscito (nessun contesto)
<?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>
elemento di risposta | |||
Nome tag | risposta | ||
Attributi dell'elemento | |||
Nome attributo | Obbligatorio? | Valore | Esempio |
successo | S | In entrambi i casivero ofalse, che indica se la chiamata API è riuscita o meno. Anche le chiamate riuscite possono contenere messaggi di avviso nella risposta. | vero |
Contenuto dell'elemento | |||
Un singolo facoltativoelemento messaggi | |||
elemento messaggi | |||
Nome tag | messaggi | ||
Descrizione | Contenitore per uno o piùelementi del messaggio | ||
Attributi dell'elemento | |||
(nessuno) | |||
Contenuto dell'elemento | |||
Uno o piùelementi del messaggio | |||
elemento messaggio | |||
Nome tag | messaggio | ||
Descrizione | Rappresenta un messaggio inviato dal sistema al chiamante. I messaggi vengono utilizzati per i messaggi di errore quando le richieste non hanno esito positivo, per i messaggi di avviso quando le richieste hanno esito positivo e per i messaggi di conferma in caso di esito positivo. | ||
Attributi dell'elemento | |||
Nome attributo | Obbligatorio? | Valore | Esempio |
chiave | N | Quando viene assegnata, una chiave è un modo per identificare un particolare messaggio o tipo di messaggio, utile ai fini della registrazione automatica degli errori e del ripristino nei programmi client. Le chiavi non cambiano nelle diverse impostazioni internazionali delle richieste, anche quando cambia la lingua del messaggio. Inoltre, è improbabile che le chiavi cambino in futuro a causa di rettifiche di testo o modifiche della terminologia. | invalid-attributevalueid |
Contenuto dell'elemento | |||
| |||
elemento di contesto | |||
Nome tag | contesto | ||
Descrizione | Contenitore per uno o più elementi colonne. | ||
Attributi dell'elemento | |||
Nome attributo | Obbligatorio? | Valore | Esempio |
nessuno | |||
Contenuto dell'elemento | |||
Uno o più elementi colonne. | |||
elemento col | |||
Nome tag | col | ||
Descrizione | Rappresenta il contesto del messaggio. Fornisce una coppia intestazione/valore per identificare la riga che genera il messaggio. | ||
Attributi dell'elemento | |||
Nome attributo | Obbligatorio? | Valore | Esempio |
intestazione | S | L'intestazione della colonna. | "Account" |
valore | S | Il valore nella colonna. | "GL-29482-38233" |
Contenuto dell'elemento | |||
(nessuno) | |||