updateAttributes

Adaptive Planning

updateAttributes

Supportato nell'API v20 +

Categoria	Modifica dei metadati
Descrizione	Aggiornare un insieme di attributi esistenti, i relativi valori e le relative proprietà. È possibile aggiornare più attributi con più valori attributo in un'unica chiamata. In caso di esito positivo, l'API restituisce i dettagli per gli attributi che sono stati aggiornati/creati. Se l'API non riesce, viene restituito un elenco completo degli errori e delle relative cause.
Autorizzazioni necessarie per richiamare	Modello
Parametri obbligatori su richiesta	Credenziali

La richiesta di questo metodo contiene un tag delle credenziali per identificare e autorizzare l'utente chiamante. L'utente deve avere il "Modello" Concetto: Set di autorizzazioni e l'autorizzazione richiesta per amministrare gli attributi da aggiornare.

Procedura consigliata: richiamare exportAttributes per recuperare il file

Adaptive Planning

ID attributo necessari per la richiesta updateAttributes. Fare del proprio meglio per ridurre al minimo il tempo tra le chiamate exportAttributes e le chiamate updateAttributes.

HTTP	Descrizione
Method	Post
Content-Type	text/xml

Esempio di arricciatura


curl -H "Content-Type: text/xml" -d @C:/temp/updateAttributes.xml -X POST https://api.adaptiveplanning.com/api/v20

updateAttributes.xml

Formato richiesta

Update a set of existing attributes and their attribute values, and their
<?xml version='1.0' encoding='UTF-8'?>
<call method="updateAttributes" callerName="a string that identifies your client application">
<credentials login="sampleuser@company.com" password="my_pwd"/>
<attributes proceedWithWarnings="0">
  <attribute id="13" name="AP Eligible" type="account" keepSorted="1">
    <attributeValue id="118" name="No" />
    <attributeValue id="117" name="Yes">
      <attributeValue id="136" name="Full" />
      <attributeValue id="135" name="Partial" />
    </attributeValue>
  </attribute>
  <attribute id="11" name="Product Line" type="account">
    <attributeValue id="34" name="A" />
    <attributeValue id="35" name="B" />
  </attribute>
  <attribute id="9">
    <attributeValue id="56" name="Available" />
    <attributeValue id="54" name="Not Applicable" />
  </attribute>
</attributes>
</call>

Per i payload di grandi dimensioni, è possibile pubblicare file XML compressi (compressi). Scopri come fare qui.

Per updateAttributes si applicano le seguenti condizioni:

Gli attributi vengono identificati per l'aggiornamento tramite il loro numero ID interno.

Per creare nuovi attributi, assegnare loro una proprietà ID vuota o mancante.

È possibile spostare un elemento esistente (non nuovo) in modo che diventi figlio di un nuovo elemento. In questo modo si crea il nuovo elemento e si sposta l'elemento esistente sotto di esso come figlio.

Formato richiesta per la creazione di un nuovo attributo

Per creare un nuovo attributo,

AP Eligible

, lasciare vuoto l'ID e specificarne il nome e il tipo.


<?xml version='1.0' encoding='UTF-8'?>
<call method="updateAttributes" callerName="Steve C">
  <credentials login="sampleuser@company.com" password="my_password"/>
    <attributes>
      <attribute id="" name="AP Eligible" type="account">
        <attributeValue id="" name="No" />
        <attributeValue id="" name="Yes">
          <attributeValue id="" name="Full" />
          <attributeValue id="" name="Partial" />
        </attributeValue>
      </attribute>
  </attributes>
</call>

Richiesta di creazione di un nuovo attributo per una dimensione elenco

Per creare un nuovo attributo

Education Type

per una dimensione elenco,

Education.

I valori degli attributi

Technical

e il figlio

Tech1,

hanno ID vuoti, a indicare che sono nuovi


<?xml version="1.0" encoding="UTF-8"?>
<call method="updateAttributes" callerName="Steve C">
<credentials login="sampleuser@company.com" password="my_password" />
 <attributes>
      <attribute id="" name="Education Type" type="dimension" listDimensionName="Education" keepSorted="1" importAutoCreateValues="1">
          <attributeValue id="" name="Technical" description="">
              <attributeValue id="" name="Tech1" description="" />
          </attributeValue>
          <attributeValue id="" name="Management" description="" />
      </attribute>
 </attributes>
</call>

Formato richiesta per la creazione di un nuovo valore attributo

future

sotto il

AP Eligible

attributo con

id 13

e il valore dell'attributo

con

id 118

, è possibile utilizzare:


<?xml version='1.0' encoding='UTF-8'?>
<call method="updateAttributes" callerName="Steve C">
  <credentials login="sampleuser@company.com" password="my_password"/>
  <attributes>
    <attribute id="13">
      <attributeValue id="118" >
        <attributeValue id="" name="future" />
      </attributeValue>  
      </attribute>
    </attributes>
</call>
To create a new attribute value, include its parent by its ID. For example, to add a new
      attribute value

Questo metodo non modifica nulla per l'attributo

id 13

. Crea un nuovo valore attributo

future

per attributo

id 13

e imposta il padre come valore attributo

. Tutti i valori attributo non menzionati di

spostarsi alla fine della lista valori. Equivale a "impostare il padre" per il nuovo valore attributo.

Gestione di più rinominazioni in un'unica chiamata updateAttributes

In un sistema remoto possono essere eseguite più rinominazioni della stessa entità

updateAttributes

chiamate I nomi delle entità nel sistema remoto possono essere scambiati con gli stessi ID entità. Quando

updateAttributes

le chiamate avvengono dopo lo scambio del nome, il

updateAttributes

call gestisce queste modifiche monitorando gli ID delle modifiche al nome. La chiamata può anche gestire l'introduzione di un nuovo ID che utilizza un nome esistente.

Affinché ciascuno degli esempi abbia esito positivo, è necessario che avvenga lo scambio completo degli ID con i valori univoci.

Esempio 1: un semplice scambio di nomi nel sistema remoto.

To create a new attribute value, include its parent by its ID. For example, to add a new
ID     Unique Value   New Unique Value
1      AA             BB
2      BB             AA

Esempio 2: una sequenza di tre rinominazioni nel sistema remoto.


ID     Unique Value   New Unique Value
1      AA             BB
2      BB             CC
3      CC             AA

Esempio 3: una nuova entità che utilizza un valore univoco esistente.


ID     Unique Value   New Unique Value
4                     AA
1      AA             BB
2      BB             Old BB

elemento credenziali
Nome tag		credenziali
Descrizione		Tutte le chiamate API devono contenere un singolo elemento di credenziali 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
accedere	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 mesi 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 attributi
Nome tag		attributi
Descrizione		È consentita una sola richiesta di elemento attributi per payload. Contiene uno o più elementi attributo.
Attributi dell'elemento
Nome attributo	Obbligatorio?	Valore	Esempio
procedereWithWarnings	N	Si applica solo quando si ridefiniscono i valori attributo. Se sono presenti avvisi e proceWithWarnings=0, il valore attributeValue non verrà aggiornato. Impostare proceWithWarnings=1 per aggiornare l'attributoValue quando sono presenti avvisi. Si applica solo a type=account e type=level. ProceedWithWarnings=1 (a) la creazione di nuovo padre viene eseguita anche quando la codifica degli attributi di conto/livello diventa incompatibile . (b) Tutti i tagging degli attributi di conto/livello incompatibili verranno corretti utilizzando il tagging degli attributi del padre. ProceedWithWarnings=0 errori se la nuova parentela del valore attributo renderebbe incompatibile la mappatura degli attributi conto/livello.	1
retainExistingOrder Disponibile nell'API v27+	N	retainExistingOrder="1" indica che l'API updateAttributes deve ignorare l'ordine degli elementi nel payload XML e l'ordine definito esistente verrà mantenuto. retainExistingOrder="0" indica che l'API updateAttributes deve aggiornare l'ordine degli elementi in base alla posizione del tag rispetto ad altri elementi di pari livello nel payload XML. Il flag retainExistingOrder viene ignorato quando l'attributo ha il flag keepSorted abilitato. Il valore predefinito per retainExistingOrder è "1".	1
DisplayNameEnabled Disponibile solo nell'API v30+ per le istanze che abilitano il nome visualizzato.	N	displayNameEnabled=1 indica che updateAttribues deve rispettare le proprietà del nome visualizzato di code , displayNameType e description quando Abilita nome visualizzato è attivo per l'istanza. displayNameEnabled=0 indica che l'API updateAttributes deve continuare a seguire il contratto API precedente alla v30 anche quando l'opzione Abilita nome visualizzato è attiva per l'istanza. L'API updateAttributes ignora le proprietà del nome visualizzato code , displayNameType e description . Il valore predefinito per displayNameEnabled è "0".	1
Contenuto dell'elemento
Contiene uno o più elementi attributo.

elemento attributo
Nome tag		attributo
Descrizione		Specifica un attributo da creare o aggiornare.
Attributi dell'elemento
Nome attributo	Obbligatorio?	Valore	Esempio
ID	S	Il numero ID sistema interno per l'attributo.	16
nome Aggiornato nell'API v30	S	Il nome dell'attributo, come appare nei report e nei fogli.	Attività correnti
codice Disponibile nell'API v39+.	N	Il codice dell'attributo	Attività correnti
displayNameType Disponibile solo nell'API v30+ per le istanze che abilitano il nome visualizzato.	N	Controlla la visualizzazione dei valori degli attributi. I valori possibili sono NAME, CODE, NAME_CODE o CODE_NAME. Il valore predefinito è NAME se lasciato vuoto o non specificato. Questa proprietà è disponibile solo quando Abilita nome visualizzato è su ON per l'istanza.	"CODE_NAME"
importAutoCreateValues	N	"1" significa che i valori attributo per questo attributo possono essere creati tramite l'importazione, "0" (o non specificato) significa che non è possibile.	1
type	N	Indica se l'attributo è un attributo di livello, conto o dimensione. Obbligatorio per creare nuovi attributi che non esistono già nel sistema. Il tipo non può essere modificato da un'operazione di aggiornamento.	account
listDimensionName	N	Indica se la dimensione è una dimensione elenco semplice. Applicabile solo quando tipo di attributo=dimensione. listDimensionName non può essere modificato da un'operazione di aggiornamento.	colore
keepSorted	N	"1" indica che i valori per questo attributo sono sempre ordinati in ordine alfabetico. "0" (o non specificato) indica che i valori degli attributi vengono ordinati in base alla loro posizione nel payload della richiesta. Il valore predefinito è "0" solo nell'operazione di creazione quando non viene specificato alcun valore. Se l'XML contiene sia il padre sia almeno un fratello di un valore attributo gerarchico non elencato, il valore non elencato viene spostato alla fine dei fratelli elencati durante l'aggiornamento (nel riordino dei figli del padre, tutti i fratelli elencati vengono prima, in nell'ordine in cui sono specificati nell'XML. Tutti i fratelli non elencati sono ultimi, nell'ordine in cui sono già presenti nel sistema). keepSorted si applica ai figli di ogni valore attributo padre. Eventuali modifiche ai componenti di un nome visualizzato potrebbero alterare l'ordinamento degli elementi, quando l'opzione Mantieni ordinamento è abilitata.	1
shortName Disponibile solo nell'API v30+ per le istanze che abilitano il nome visualizzato.	N	Il nome abbreviato dell'attributo. La lunghezza massima dei caratteri è 64. Disponibile solo quando l'opzione Abilita nome visualizzato è attiva per l'istanza.	Attività
descrizione Disponibile solo nell'API v30+ per le istanze che abilitano il nome visualizzato.	N	La descrizione dell'attributo. La lunghezza massima dei caratteri è 2048. Valore predefinito: vuoto Questa proprietà è disponibile solo quando Abilita nome visualizzato è su ON per l'istanza.	Attività
Contenuto dell'elemento
Uno o più elementi attributeValue.

elemento attributeValue
Nome tag		attributeValue
Descrizione		Specifica i valori degli attributi da creare o aggiornare.
Attributi dell'elemento
Nome attributo	Obbligatorio?	Valore	Esempio
ID	N	Identifica il valore dell'attributo. Se lasciato vuoto, indica un nuovo valore attributo creato dalla richiesta.	24
codice Disponibile solo nell'API v30+ per le istanze che abilitano il nome visualizzato.	N	Il codice univoco del valore dell'attributo.	sì
nome Aggiornato nell'API v30	S	Il nome del valore dell'attributo, così come appare nei fogli e nei report. Quando l'opzione Abilita nome visualizzato è attiva per un'istanza con API v30 o successiva, il nome consente valori duplicati. Quando l'opzione Abilita nome visualizzato è disattivata per un'istanza, il codice non è disponibile e il nome deve essere univoco. Nomi valori attributo non validi: nomi che terminano con (+) o (-)	sì
descrizione	N	La descrizione testuale del valore dell'attributo. Valore predefinito: vuoto Il valore predefinito viene utilizzato nell'operazione di creazione solo quando non viene specificato alcun valore.
Contenuto dell'elemento
Può contenere un altro attributeValue.

Formato risposta


<?xml version="1.0" encoding="UTF-8"?>
<response success="true">
<messages>
  <message type="INFO">Attributes were saved successfully.</message>
</messages>
<output>
    <attributes>
      <attribute id="13" name="AP Eligible" type="account">
        <attributeValue id="118" name="No" />
        <attributeValue id="117" name="Yes">
          <attributeValue id="136" name="Full" />
          <attributeValue id="135" name="Partial" />
        </attributeValue>
      </attribute>
      <attribute id="11" name="Product Line" type="account">
        <attributeValue id="34" name="A" />
        <attributeValue id="35" name="B" />
      </attribute>
      <attribute id="9" name="Corporate Discount" type="level">
        <attributeValue id="56" name="Available" />
        <attributeValue id="54" name="Not Applicable" />
        <attributeValue id="57" name="Not Available" />
        <attributeValue id="55" name="TBD" />
      </attribute>
      <attribute id="10" name="Tax Code" type="level">
        <attributeValue id="146" name="TT-PYT" />
        <attributeValue id="145" name="TT-TRE" />
      </attribute>
      <attribute id="16" name="Industry" type="dimension" listDimensionName="Education">
        <attributeValue id="335" name="Apparel">
           <attributeValue id="354" name="Mens Apparel" />
           <attributeValue id="355" name="Shoes" />
           <attributeValue id="356" name="Womens Apparel" />
        </attributeValue>
      </attribute>
    </attributes>
  </output>
</response>

elemento di output
Nome tag	output
Attributi dell'elemento
(nessuno)
Contenuto dell'elemento
Un singolo elemento attributi obbligatori. Questo wrapper di output è standard in tutte le risposte API e racchiude l'output valido di qualsiasi chiamata API riuscita.

elemento attributi
Nome tag		attributi
Descrizione		Contenitore per zero o più elementi attributo. I tag vengono ordinati in base alla richiesta di input.
Attributi dell'elemento
Nome attributo	Obbligatorio?	Valore	Esempio
procedereWithWarnings	N	ProcediWithWarnings specificato nella richiesta API.	1
retainExistingOrder	N	updateAttributes=0 aggiorna l'ordinamento in base al contenuto del payload XML. updateAttributes=1 mantiene l'ordinamento esistente.	1
displayNameEnabled Disponibile solo nell'API v30+ per le istanze che abilitano il nome visualizzato.	N	displayNameEnabled=1 indica che updateAttributes deve rispettare le proprietà del nome visualizzato di code , displayNameType e description quando Abilita nome visualizzato è attivo per l'istanza. displayNameEnabled=0 indica che l'API updateAttribues deve continuare a seguire il contratto API precedente alla versione 2021.42 anche quando l'opzione Abilita nome visualizzato è attiva per l'istanza. L'API updateAttribues ignora le proprietà del nome visualizzato code , displayNameType e description . Il supporto per displayNameEnabled è iniziato nel 2021.42. Il valore predefinito per displayNameEnabled è "0".	1
Contenuto dell'elemento
Uno o più elementi attributo.

elemento attributo
Nome tag		attributo
Descrizione		Rappresenta un singolo attributo restituito nella risposta a una chiamata API updateAttributes.
Attributi dell'elemento
Nome attributo	Obbligatorio?	Valore	Esempio
ID	S	Il numero ID sistema interno per l'attributo.	16
nome	S	Il nome dell'attributo, come appare nei report e nei fogli.	Attività correnti
codice Disponibile nell'API v39+.	S	Il codice dell'attributo.	Attività correnti
shortName		Il nome abbreviato dell'attributo. La lunghezza massima dei caratteri è 2048.	Attività
displayNameType Disponibile solo nell'API v30+ per le istanze che abilitano il nome visualizzato.	N	Controlla la visualizzazione dei valori degli attributi. I valori possibili sono NAME, CODE, NAME_CODE o CODE_NAME. Il valore predefinito è NAME se lasciato vuoto o non specificato. Questa proprietà è disponibile solo quando Abilita nome visualizzato è su ON per l'istanza.	CODE_NAME
importAutoCreateValues	N	"1" significa che i valori attributo per questo attributo possono essere creati tramite l'importazione, "0" (o non specificato) significa che non è possibile.	1
type	S	Il tipo dell'attributo. Sarà "conto" se l'attributo è per un conto, "livello" se l'attributo è per un livello o "dimensione" se l'attributo è per una dimensione.	account
listDimensionName	N	Il nome della dimensione elenco se l'attributo è di tipo "dimensione".	Istruzione
descrizione	N	La descrizione testuale dell'attributo, se presente, immessa in Amministrazione attributi	Totale attività correnti
keepSorted	S	"1" indica che i valori per questo attributo sono sempre ordinati in ordine alfabetico. "0" (o non specificato) indica che i valori degli attributi vengono ordinati in base alla loro posizione nel payload della richiesta. Se l'XML contiene sia il padre sia almeno un fratello di un valore attributo gerarchico non elencato, il valore non elencato viene spostato alla fine dei fratelli elencati durante l'aggiornamento (nel riordino dei figli del padre, tutti i fratelli elencati vengono prima, in nell'ordine in cui sono specificati nell'XML. Tutti i fratelli non elencati sono ultimi, nell'ordine in cui sono già presenti nel sistema). keepSorted si applica ai figli di ogni valore attributo padre.	1
stato	S	Lo stato del valore dell'attributo dopo l'aggiornamento. Per gli avvisi e gli errori, l'elemento del messaggio contiene il contenuto del messaggio. Lo stato di aggiornamento non restituisce alcun contenuto del messaggio. Errore: è stato rilevato un errore nell'entità Avviso: è stato trovato un avviso nell'entità Created: l'entità è stata creata Aggiornato: l'entità è stata aggiornata	Aggiornato
messaggio	N	Il messaggio di errore per l'input dell'attributo.	L'attributo Settore è duplicato nel payload o esiste già nel sistema con ID 8
Contenuto dell'elemento
Zero o più elementi attributeValue facoltativi. Ogni elemento attributeValue racchiuso rappresenta un "valore attributo radice" nell'attributo, un valore che non ha un valore padre.

elemento attributeValue
Nome tag		attributeValue
Descrizione		Rappresenta un singolo valore membro di un attributo restituito nella risposta a una chiamata API updateAttributes.
Attributi dell'elemento
Nome attributo	Obbligatorio?	Valore	Esempio
ID	S	Il numero ID sistema interno per questo valore membro dell'attributo.	34
codice Disponibile solo nell'API v30+ per le istanze che abilitano il nome visualizzato.	N	Il codice univoco del valore dell'attributo.	Disponibile
nome	S	L'etichetta per il valore membro dell'attributo visualizzato nella pagina di amministrazione degli attributi.	Disponibile
shortName	N	Il nome abbreviato del valore attributo.	Avl
descrizione	N	La descrizione del valore dell'attributo. Valore predefinito: vuoto Il valore predefinito viene utilizzato nell'operazione di creazione solo quando non viene specificato alcun valore.
propogateToDescendants	N	Indica se le modifiche vengono propagate ai figli di questo livello. 0 per no, 1 per sì.	0
stato	S	Lo stato dell'attributo dopo l'aggiornamento. Per gli avvisi e gli errori, l'elemento del messaggio contiene il contenuto del messaggio. Lo stato di aggiornamento non restituisce alcun contenuto del messaggio. Errore: è stato rilevato un errore nell'entità Avviso: è stato trovato un avviso nell'entità Created: l'entità è stata creata Aggiornato: l'entità è stata aggiornata	aggiornato
messaggio	N	Il messaggio di errore per un input attributeValue non valido.
Contenuto dell'elemento
Zero o più elementi attributeValue facoltativi. Ogni elemento attributeValue racchiuso rappresenta un "valore attributo figlio" di questo valore attributo, i cui membri eseguono implicitamente il rollup a questo valore.