customReportValues

Adaptive Planning

customReportValues

Aggiornato nell'API v37.

Categoria	Recupero dei dati
Descrizione	Restituisce un insieme di dati per i criteri di report richiesti nell'istanza richiesta.
Autorizzazioni necessarie per richiamare	Nessuno (all'utente deve essere assegnato un set di autorizzazioni)
Parametri obbligatori su richiesta	Credenziali, Report

Per l'API versione 15 e successive, chiamare exportTime per recuperare gli ID degli elementi temporali corretti

Consultare Riferimenti: condizioni di performance di customReportValues per informazioni su come garantire che le richieste sfruttino i miglioramenti delle prestazioni e della scalabilità rilasciati nella versione 2023R2 per l'API v36.

La richiesta di questo metodo contiene una specifica per un report che può essere utilizzata per cercare dati e restituire valori. L'API accetta i numeri ID interni come input. È possibile richiamare le API di recupero dei metadati per ottenere ID validi. I risultati sono rappresentati da coordinate e valori. La risposta restituisce anche avvisi e messaggi di errore, se applicabile.

Questa API si basa sui report matrice. La richiesta richiede che il chiamante specifichi gli elementi sull'asse X (colonne), sull'asse Y (righe) e su un asse filtro facoltativo utilizzato per filtrare tutti i dati recuperati dall'API. I report matrice contengono assi che determinano i dati da visualizzare nel report. Ogni asse definisce un bordo del report. Tutti i report matrice hanno tre assi:

l'asse X (il bordo superiore). Definisce l'insieme di colonne del report.

l'asse Y (il bordo sinistro). Definisce l'insieme di righe di un report

l'asse del filtro, un asse globale che definisce le proprietà applicabili a tutti i dati del report. Per ulteriori informazioni, consultare gli esempi degli assi dei filtri.

Un asse può essere suddiviso in più segmenti. Un segmento è un modo per separare insiemi di dimensioni su un singolo asse. L'asse del filtro può avere un solo segmento, ma gli altri due assi possono avere tutti i segmenti desiderati.

Ogni segmento può avere un numero illimitato di scaglioni. Uno scaglione rappresenta una singola dimensione logica utilizzata per descrivere quali elementi di tale dimensione si applicano alle righe o alle colonne sottostanti. Un segmento può contenere al massimo uno scaglione per dimensione logica.

Ogni scaglione può contenere uno o più elementi della dimensione dello scaglione. Tutti gli elementi dello scaglione devono appartenere alla dimensione specificata nello scaglione. Un elemento è in genere un elemento nella dimensione, ad esempio un conto particolare nella dimensione conto o un trimestre fiscale nella dimensione temporale. Questi elementi vengono quindi utilizzati dal sistema per selezionare e aggregare i dati presenti nel report.

Quando un segmento sull'asse X o Y contiene più scaglioni, gli elementi di ogni scaglione vengono combinati con tutti gli elementi di tutti gli altri scaglioni per formare il prodotto cartesiano di tutte le possibili combinazioni di elementi dello scaglione. Ogni colonna o riga rappresenta una possibile combinazione di elementi, selezionando un elemento da ogni scaglione. Ad esempio, se un segmento sull'asse X, le colonne nella parte superiore, contiene uno scaglione con cinque elementi e un secondo scaglione con due elementi, il segmento risulterà in dieci colonne separate, che rappresentano tutte le possibili combinazioni degli elementi gli scaglioni Non è possibile posizionare un tipo di elemento su più assi. Ad esempio, se si inserisce il tipo di elemento conto nelle righe, non è possibile aggiungere conti nelle colonne o nei filtri.

Uno scaglione può avere sia elementi singoli sia elementi di rollup. Gli elementi di rollup eseguono il rollup arbitrario di tutti gli elementi specificati sotto di essi. Gli elementi di rollup non sono consentiti nel filtro.

L'asse del filtro si comporta in modo molto simile agli assi X e Y, ma presenta una leggera differenza: poiché si applica a tutti i dati del report, non può combinare i livelli per formare più righe o colonne. Al contrario, l'asse del filtro combina tutti gli elementi di ogni scaglione, aggregando i dati di tutti gli elementi come se tali elementi stessero effettuando il rollup a un'unica aggregazione.

Consultare Creare report matrice di base per ulteriori informazioni su segmenti, assi ed elementi dimensionali.

Filtrare esempi di assi

L'esempio seguente mostra tutti i possibili elementi per l'asse del filtro.


<axis type="FILTER">
    <segment>
<!-- Account filter -->
        <tier type="acct">
            <el id="258" />
        </tier>
<!-- Time filter -->
        <tier type="time">
            <el id="342" />
        </tier>
<!-- Level filter -->
        <tier type="lvl">
            <el id="354" />
        </tier>
<!-- Version filter -->
        <tier type="ver">
            <el id="385" offset="1" offset-strata="2"/>
        </tier>
<!-- Currency filter -->
        <tier type="cur">
            <el id="448" />
        </tier>
<!-- Account Attribute filter -->
        <tier entity-id="23" type="aAttr">
            <el id="512" />
        </tier>
<!-- Level Attribute filter -->
        <tier entity-id="25" type="lAttr">
            <el id="607" />
        </tier>
<!-- Dimension Attribute filter -->
        <tier entity-id="21" type="dAttr">
            <el id="649" />
        </tier>
<!-- Dimension filter -->
        <tier entity-id="1" type="dim">
            <el id="717" />
        </tier>
    </segment>
</axis>

Formato richiesta

Lo schema XML per la richiesta è disponibile qui: customReportValues REST Specification.

<?xml version='1.0' encoding='UTF-8'?>
     <call method="customReportValues" callerName="a string that identifies your client application">
        <credentials login="sampleuser@company.com" password="my_pwd" locale="fr_FR" instanceCode="INSTANCE1"></credentials>
        <requestInfo>
           <!-- Add elements here that we want to show up in the ELK logs -->
        </requestInfo>
        <report suppress-zeroes="1" include-element-code="1"> <!-- Run report suppressing blanks, but not zero values. Add calc element codes to the response -->
            <!-- columns -->
            <axis type="X">
                <segment>
                    <!-- time columns -->
                    <tier type="time">
                        <!-- Timespan creates multiple time columns from Jan-2014 to Dec-2014.Ids specified in timespan element are retrieved from exportTime API output.  
                             'show-time' is a mandatory attribute specifying list of strata ids -->
                        <el complex-type="timespan" end="179001" start="168001" show-time="3,2,1"/>
                        <el id="180001" /> <!-- single column of Jan 2015 . This id is retrieved from exportTime API output-->
                        <subtotal code="Subtotal" /> <!-- subtotal of the output of all the time elements left of this subtotal element -->
                    </tier>
                </segment>
            </axis>
            <!-- rows -->
            <axis type="Y">
                <segment>
                    <!-- There are 2 tiers with 2 elements and 4 elements, respectively. Without considering expansion, this generates 8 rows of:
                         1. dimension value with id 135, account with id 51
                         2. dimension value with id 135, account with id 53
                         3. dimension value with id 135, difference between account with id 51 and account with id 53
                         4. dimension value with id 135, calculation using the formula - Sum of account with id 51 and the output of the difference element from previous row
                         5. dimension value with id 199, account with id 51
                         6. dimension value with id 199, account with id 53
                         7. dimension value with id 199, difference between account with id 51 and account with id 53
                         8. dimension value with id 199, calculation using the formula - Sum of account with id 51 and the output of the difference element from previous row. 
                         
                         Assume dimension value 135 has child 150, which has children 160,161,162. Dimension value 199 has child 200, which has children 210,211,212. 
                         With expansion, element of dimension value 135 with rollup-mode 'D' and 'suppress-elt-rollup' would yield to {135,160,161,162}.
                         Element of dimension value 199 with 'rollup-mode' 'X' and 'start-expanded' 199,200 would yield to {199,200,210,211,212}.
                         In total, there will be 9 x 4 = 36 rows in cartesian without suppress zero. 
                    -->
-
                    <tier entity-id="13" type="dim"> <!-- dimension values with id 135 and 199 from dimension with id of 13 -->
                        <el id="135" rollup-mode="D" suppress-elt-rollup="1"/> <!-- Expand to Leaves operation on tag dimension id=135, return "Leaves + root" -->
                        <el id="199" rollup-mode="X" start-expanded="199,200"/> <!-- Custom expansion with start expanded on tag dimension id=199 and 200, where 200 is a child of 199, return 199 and the the immediate children of 199 and 200 --> 
                    </tier>
                    <tier type="acct"> <!-- account with id of 51 and 53 -->
                        <el id="51" />
                        <el id="53" />                        
                        <diff operand-a="51" operand-b="53" code="Difference" /> <!-- difference between account with id 51 and account with id 53 -->
                        <calc formula="[51]+RPT.Difference" /> <!-- calculation using the formula - Sum of account with id 51 and the output of the difference element (previous element) -->
                    </tier>
                 </segment>
            </axis>
        </report>
    </call>

Ogni chiamata di questa chiamata API deve contenere esattamente un elemento di ciascuno dei tipi elencati:

credenziali

report

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 del report

Nome tag

report

Descrizione

Specifica gli elementi che compongono il report.

Attributi dell'elemento

Nome attributo

Obbligatorio?

Valore

Esempio

soppressione-zeri

Aggiornato nell'API v37.

Questo attributo determina la soppressione a livello di riga. La specificazione determina se l'output contiene o meno righe vuote o zero. I valori validi sono 0 (Elimina vuoto - Mostra tutte le righe), 1 (Elimina spazio vuoto - Elimina righe che contengono solo celle vuote) e 2 (Elimina spazio vuoto e zero - Elimina righe che contengono solo celle vuote o zero). Se questo attributo non è specificato, il valore predefinito è 2. Una cella viene considerata vuota se il valore di Esplora celle per tale cella è vuoto.

Questo attributo funziona insieme all'attributo "cell-inclusions". Consultare "cell-inclusions" per verificare il comportamento predefinito.

cell-inclusions

Disponibile nell'API v37.

Questo attributo determina la soppressione a livello di cella per tutte le righe non eliminate, come indicato dall'attributo "suppress-zeri". Se si specifica questa opzione, l'output conterrà o meno celle vuote o zero. I valori validi sono 0 (Includi tutto - mostra tutte le celle), 1 (Includi dati e zero - Escludi celle vuote) e 2 (Includi solo dati - Escludi zero e celle vuote).

Comportamento predefinito: se questo attributo non è specificato, il comportamento predefinito è determinato dall'attributo "suppress-zeroes". Comportamento per diversi valori di attributo "suppress-zeri":

"suppress-zeroes"	"Comportamento di inclusione di celle (valore)
0	Includi tutte le celle (0)
1	Includi dati e zero celle (1)
2	Includi solo celle dati (2)

show-cell-notes

Quando viene specificato, questo attributo mostra o nasconde le note della cella. 0=Non mostrare le note della cella (impostazione predefinita), 1=mostra le note della cella

sopprimere i rollup

Quando viene specificato, questo attributo mostra o nasconde le righe e le colonne di rollup. Le righe e le colonne di rollup vengono eliminate solo per gli elementi padre i cui figli sono presenti nel report. I valori validi sono 0 (Non sopprimere i rollup) o 1 (Non sopprimere i rollup). Il valore predefinito è 0.

include-element-code

Quando viene specificato, questo attributo aggiunge o nasconde i codici degli elementi Calc (Subtotale, Difference e Calculation). I valori validi sono 0 (Non aggiungere codici all'output per gli elementi di calcolo) o 1 (Aggiungi codici all'output per gli elementi di calcolo). Il valore predefinito è 0.

Contenuto dell'elemento

Per ulteriori dettagli, fare riferimento a Formato richiesta.

Formato risposta

Lo schema XML per la risposta è disponibile in customReportValues REST Specification.


<?xml version="1.0" encoding="utf-8"?>
<response success="true">
   <messages>
       <!-- Dimension value id 13 is invalid. Rows with value id 13 has been removed from the report. -->
       <message type="WARNING" key="invalid-dim-attr-id" values="199,13">Invalid value Id
           199 for dimension/attribute type id 13
       </message>
   </messages>
   <!-- Global filters. Although the request did not supply any filters, defaults are used when dimension types are not
       specified. Reporting against version with id 2 which is the current version. Level with id 1 is the top most level this user
       has access to. -->
   <filters>
       <coords>
           <coord type="ver" rollup="1">
               <el id="2" />
           </coord>
           <coord type="lvl" rollup="1">
               <el id="1" />
           </coord>
       </coords>
   </filters>
   <!-- Only two time columns Dec-2014 and Jan-2015 have data, all other columns have been removed -->
   <cols>
       <col id="1">
           <coords>
               <coord type="time">
                   <el id="179001" />
               </coord>
           </coords>
       </col>
       <col id="2">
           <coords>
               <coord type="time">
                   <el id="180001" />
               </coord>
           </coords>
       </col>
       <col id="3">
           <coords>
               <coord code="Subtotal" type="subtotal" />
           </coords>
       </col>
   </cols>
   <rows>
       <row>
           <!-- Row coordinates are account with id 51 and dimension value with id of 135 from dimension with id of 13 -->
           <coords>
               <coord type="acct">
                   <el id="51" />
               </coord>
               <coord type="dim" entity-id="13">
                   <el id="135" />
               </coord>
           </coords>
           <cell value="2.345" col="1" /> <!-- This value’s coordinates are the row coordinates listed above, matches column position 1 and the global filters. -->
           <cell value="2.345" col="2" /> <!-- This value’s coordinates are the row coordinates listed above, matches column position 2 and the global filters. -->
           <cell value="4.69" col="3" /> <!-- This value’s coordinates are the row coordinates listed above, matches column position 2 and the global filters. -->
       </row>
       <row>
           <!-- Row coordinates are account with id 53 and dimension value with id of 135 from dimension with id of 13 -->
           <coords>
               <coord type="acct">
                   <el id="53" />
               </coord>
               <coord type="dim" entity-id="13">
                   <el id="135" />
               </coord>
           </coords>
           <cell value="5.34" col="1" /> <!-- This value’s coordinates are the row coordinates listed above, matches column position 1 and the global filters. -->
           <cell value="7.44" col="2" /> <!-- This value’s coordinates are the row coordinates listed above, matches column position 2 and the global filters. -->
           <cell value="12.78" col="3" /> <!-- This value’s coordinates are the row coordinates listed above, matches column position 2 and the global filters. -->
       </row>
       <row>
           <coords>
               <coord code="Difference" type="diff" />
               <coord type="dim" entity-id="13">
                   <el id="135" />
               </coord>
           </coords>
           <cell value="2.995" col="1" />
           <cell value="5.095" col="2" />
           <cell value="8.09" col="3" />
       </row>
       <row>
           <coords>
               <coord type="calc" />
               <coord type="dim" entity-id="13">
                   <el id="135" />
               </coord>
           </coords>
           <cell value="5.34" col="1" />
           <cell value="7.44" col="2" />
           <cell value="12.78" col="3" />
       </row>
   </rows>
</report>
</output>
</response>

elemento di risposta
Nome tag		risposta
Attributi dell'elemento
Nome attributo	Obbligatorio?	Valore	Esempio
successo	S	Vero o falso, a indicare se la chiamata API è riuscita o meno. Anche le chiamate riuscite possono contenere messaggi di avviso nella risposta.	true
obsoleto	N	Se presente nel tag di risposta e impostato su true, questo attributo indica che la versione del metodo o dell'API richiamata è diventata obsoleta ed è ufficialmente obsoleta. Sebbene continui a funzionare in questo momento, potrebbe cessare di funzionare in breve tempo. In genere, questo attributo non è presente.	falso
Contenuto dell'elemento
Un singolo elemento di messaggi facoltativo ed esattamente un elemento di output obbligatorio.

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
type	S	Il tipo è un metodo per identificare il tipo di messaggio. I diversi tipi sono INFO, WARNING ed ERROR. Il tipo "ERRORE" indica che la richiesta non è stata elaborata.	AVVISO
chiave	S	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.	warning-invalid-time-span-start
valori	N	Quando vengono specificati, i valori rappresentano le variabili utilizzate nel testo del messaggio.	199,12
Contenuto dell'elemento
Il testo del messaggio. Questo testo è nella lingua delle impostazioni internazionali specificate nella richiesta (supponendo che le impostazioni internazionali siano supportate). Il testo può anche contenere informazioni variabili come il numero di righe elaborate o la colonna o il valore specifico che ha causato un errore.

elemento di output
Nome tag	output
Descrizione
Attributi dell'elemento
(nessuno)
Contenuto dell'elemento
Per ulteriori dettagli, fare riferimento all'XML della risposta

Consultare Concetto: Sintassi delle formule e regole per i calcoli personalizzati