customReportValues

Adaptive Planning

customReportValues

Mis à jour dans API v37.

Catégorie	Récupération des données
Description	Renvoie un ensemble de données pour les critères de rapport demandés dans l'instance demandée.
Autorisations requises pour appeler	Aucun (l'utilisateur doit avoir un ensemble d'autorisations)
Paramètres obligatoires à la demande	Identifiants, Rapport

Pour l'API version 15 et les versions ultérieures, appelez exportTime pour récupérer les identifiants des éléments de temps corrects.

Voir Référence : conditions de performance de customReportValues pour savoir comment garantir que vos demandes tirent parti des améliorations en matière de performance et d'évolutivité publiées dans la version 2023R2 pour l'API v36.

La demande de cette méthode contient les spécifications d'un rapport pouvant être utilisé pour rechercher des données et des valeurs de renvoi. L'API utilise les numéros d'identification internes comme saisies. Les API de récupération des métadonnées peuvent être appelées pour obtenir des identifiants valides. Les résultats sont représentés par des coordonnées et des valeurs. La réponse renvoie également des avertissements et des messages d'erreur, le cas échéant.

Cette API repose sur les rapports matriciels. La demande exige que l'appelant indique des éléments sur un axe X (colonnes), un axe Y (lignes) et un axe de filtre facultatif utilisé pour filtrer toutes les données extraites par l'API. Les rapports matriciels contiennent des axes qui déterminent les données qui apparaissent sur le rapport. Chaque axe définit un coin du rapport. Tous les rapports matriciels comportent trois axes :

l'axe X (le coin supérieur). Il définit l'ensemble des colonnes du rapport.

l'axe Y (le coin gauche). Il définit l'ensemble des lignes du rapport.

L'axe des filtres, qui est un axe global qui définit les propriétés qui s'appliquent à toutes les données du rapport. Pour en savoir plus, voir les exemples d'axe de filtre.

Un axe peut être divisé en plusieurs segments. Un segment est un moyen de séparer des ensembles de dimensions sur un seul axe. L'axe de filtre ne peut avoir qu'un seul segment, mais les deux autres axes peuvent avoir autant de segments que vous le souhaitez.

Chaque segment peut avoir un nombre illimité de paliers. Un palier représente une dimension logique unique utilisée pour décrire quels éléments de cette dimension s'appliquent aux lignes ou aux colonnes sous-elle. Un segment ne peut contenir au maximum qu'un palier par dimension logique.

Chaque palier peut contenir un ou plusieurs éléments de sa dimension. (Tous les éléments du palier doivent appartenir à la dimension spécifiée dans le palier.) Un élément est généralement un élément de la dimension, comme un compte particulier dans la dimension de compte ou un trimestre comptable dans la dimension de temps. Ces éléments sont ensuite utilisés par le système pour sélectionner et agréger les données trouvées dans le rapport.

Lorsqu'un segment de l'axe X ou Y contient plusieurs paliers, les éléments de chaque palier sont combinés avec tous les éléments de tous les autres paliers pour former le produit cartésien de toutes les combinaisons possibles d'éléments de palier. Chaque colonne ou ligne représente une combinaison possible d'éléments, en sélectionnant un élément dans chaque palier. Par exemple, si un segment sur l'axe X (les colonnes en haut) contient un palier avec cinq éléments et un deuxième palier avec deux éléments, le segment présentera dix colonnes distinctes, représentant toutes les combinaisons possibles des éléments sur l'axe. les paliers. Vous ne pouvez pas placer un type d'élément sur plusieurs axes. Par exemple, si vous placez le type d'élément de compte sur les lignes, vous ne pourrez pas ajouter de comptes aux colonnes ou filtres.

Un palier peut avoir à la fois des éléments individuels et des éléments d'agrégat. Les éléments d'agrégat regroupent arbitrairement tous les éléments spécifiés sous eux. Les éléments d'agrégat ne sont pas autorisés dans le filtre.

L'axe de filtre se comporte de manière très similaire aux axes X et Y, mais il présente une petite différence : comme l'axe de filtre s'applique à toutes les données du rapport, il ne peut pas combiner ses paliers pour former plusieurs lignes ou colonnes. Au lieu de cela, l'axe des filtres combine tous les éléments de chaque palier, en agrégeant les données de tous les éléments ensemble, comme si ces éléments étaient agrégés dans une seule agrégation.

Voir Créer des rapports matriciels de base pour plus d'informations sur les segments, les axes et les éléments dimensionnels.

Exemples d'axe de filtre

L'exemple ci-dessous montre tous les éléments possibles pour l'axe de filtre.


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

Format de demande

Le schéma XML de la demande se trouve ici : 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>

Chaque invocation de cet appel d'API doit contenir exactement un élément de chacun des types répertoriés :

identifiants

rapport

élément identifiants
Nom du marqueur		identifiants
Description		Tous les appels d'API doivent contenir un seul élément identifiants pour identifier l'utilisateur qui a appelé l'API. L'appel d'API est ensuite effectué en tant qu'utilisateur ( n'importe quelle piste d'audit ou historique d'actions dans le système indique que cet utilisateur a effectué l'action) et, par conséquent, l'utilisateur doit avoir les autorisations requises pour effectuer l'action afin que l'appel d'API s'appelle réussir.
Attributs de l'élément
Nom de l'attribut	Obligatoire ?	Valeur	Exemple
login	O	Le nom de connexion de l'utilisateur appelant la méthode API. Cet utilisateur doit avoir les autorisations requises pour appeler la méthode	sampleuser@company.com
mot de passe	O	Mot de passe de l'utilisateur appelant la méthode API.	my_password
locale	N	Indiquez les paramètres régionaux à utiliser pour interpréter les chiffres et les dates entrants, et pour formater les chiffres et les dates sortants (en utilisant le séparateur des milliers, les noms de mois et la mise en forme de date appropriés). Les paramètres régionaux sont également utilisés pour indiquer la langue dans laquelle doivent s'afficher les messages système figurant dans la réponse. Si aucune option n'est indiquée, l'expression en_US (anglais américain) est utilisée.	fr_FR
instanceCode	N	Si l'utilisateur spécifié dans les identifiants a accès à plusieurs instances de : Adaptive Planning , cet attribut peut être utilisé pour indiquer que l'utilisateur a l'intention d'accéder à une instance autre que son instance par défaut. Si aucune option n'est indiquée, l'instance par défaut de l'utilisateur sera utilisée. Pour déterminer les codes d'instance disponibles, utilisez l'API exportInstances.	MYINSTANCE1
Contenu de l'élément
(aucun)

élément de rapport

Nom du marqueur

rapport

Description

Indique les éléments qui constituent le rapport.

Attributs de l'élément

Nom de l'attribut

Obligatoire ?

Valeur

Exemple

suppress-zeroes

Mis à jour dans API v37.

Cet attribut commande la suppression au niveau des lignes. Ce paramètre contrôlera si la sortie contient des lignes nulles ou vides. Les valeurs valides sont 0 (Supprimer rien - afficher toutes les lignes), 1 (Supprimer les lignes vides - supprimer les lignes contenant uniquement des cellules vides) et 2 (Supprimer les lignes vides et zéro - supprimer les lignes contenant uniquement des cellules vides ou nulles). Si cet attribut n'est pas spécifié, la valeur par défaut est 2. Une cellule est considérée comme vide si la valeur de l'explorateur de cellules pour cette cellule est vide.

Cet attribut fonctionne en lien avec l'attribut "cell-inclusions". Voir "Inclusions de cellules" pour vérifier le comportement par défaut.

cell-inclusions

Disponible dans API v37 et API v37.

Cet attribut commande la suppression au niveau de la cellule pour toutes les lignes non supprimées, en fonction de l'attribut "suppress-zeroes". Ce paramètre contrôlera si la sortie contient des cellules nulles ou vides. Les valeurs valides sont 0 (Inclure tout - afficher toutes les cellules), 1 (Inclure les données et zéro - exclure les cellules vides) et 2 (Inclure les données uniquement - Exclure les cellules nulles et vides).

Comportement par défaut : si cet attribut n'est pas spécifié, le comportement par défaut est déterminé par l'attribut "suppress-zeroes". Comportement des différentes valeurs d'attribut "suppress-zeroes" :

"suppress-zeroes"	"comportement d'inclusion de cellule (valeur)
0	Inclure toutes les cellules (0)
1	Inclure des cellules de données et des cellules nulles (1)
2	Inclure les cellules de données uniquement (2)

show-cell-notes

Lorsqu'il est donné, cet attribut affiche ou masque les notes de cellule. 0 = Ne pas afficher les notes de cellule (par défaut), 1 = afficher les notes de cellule

supprime les agrégats

Lorsqu'il est donné, cet attribut affiche ou masque les lignes et colonnes d'agrégat. Les lignes et colonnes d'agrégat sont supprimées uniquement pour les parents dont les enfants figurent sur le rapport. Les valeurs valides sont 0 (Ne pas supprimer les agrégats) ou 1 (Supprimer les agrégats). La valeur par défaut est 0.

include-element-code

Lorsqu'il est donné, cet attribut ajoute ou masque les codes des éléments Calcul (Sous-total, Différence et Calcul). Les valeurs valides sont 0 (ne pas ajouter de codes à la sortie pour les éléments de calcul) ou 1 (ajouter des codes à la sortie pour les éléments de calcul). La valeur par défaut est 0.

Contenu de l'élément

Pour plus d'informations, reportez-vous au Format de demande.

Format de la réponse

Le schéma XML de la réponse se trouve dans la spécification REST customReportValues.


<?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>

élément de réponse
Nom du marqueur		réponse
Attributs de l'élément
Nom de l'attribut	Obligatoire ?	Valeur	Exemple
réussite	O	Vrai ou faux, indiquant si l'appel d'API a réussi ou non. Même les appels traités avec succès peuvent contenir des messages d'avertissement dans leur réponse.	vrai
obsolète	N	S'il figure sur le marqueur de réponse et qu'il est défini sur true (vrai), cet attribut indique que la version de la méthode ou de l'API en cours d'appel est obsolète et qu'elle est officielement dépréciée. Même si elle continue de fonctionner à ce moment, elle peut cesser de fonctionner prochainement. En général, cet attribut n'est pas présent.	false
Contenu de l'élément
Un seul élément de messages facultatifs et exactement un élément de sortie obligatoire.

élément de message
Nom du marqueur	messages
Description	Conteneur pour un ou plusieurs éléments de message.
Attributs de l'élément
(aucun)
Contenu de l'élément
Un ou plusieurs éléments de message.

élément de message
Nom du marqueur		message
Description		Représente un message que le système renvoie à l'appelant. Les messages sont utilisés pour les messages d'erreur lorsque les demandes n'ont pas abouti, pour les messages d'avertissement lorsque les demandes ont abouti et pour les messages de confirmation lorsque les demandes ont abouti.
Attributs de l'élément
Nom de l'attribut	Obligatoire ?	Valeur	Exemple
type	O	Le Type est un moyen d'identifier le type de message. Les types différents sont INFO, AVERTISSEMENT et ERREUR. "Erreur" signifie que cette demande n'a pas été traitée.	AVERTISSEMENT
clé	O	Une clé est un moyen d'identifier un message ou un type de message particulier, utile à des fins de journalisation et de récupération automatiques des erreurs dans les programmes client. Les clés ne changent pas selon les paramètres régionaux des demandes, même lorsque la langue du message change. Il est également peu probable que les clés changent à l'avenir en raison d'ajustements du libellé ou de la terminologie.	Avertissement-invalide-intervalle- temps-départ
valeurs	N	Lorsqu'elles sont données, les valeurs représentent les variables utilisées dans le texte du message.	199,12
Contenu de l'élément
Texte du message. Ce texte est exprimé dans la langue des paramètres régionaux indiqués dans la demande (en supposant que les paramètres régionaux soient pris en charge). Le texte peut également contenir des informations variables telles que le nombre de lignes qui ont été traitées ou la colonne ou la valeur particulière qui a généré une erreur.

élément de sortie
Nom du marqueur	sortie
Description
Attributs de l'élément
(aucun)
Contenu de l'élément
Reportez-vous au fichier XML de réponse pour plus d'informations.

Voir Concept : syntaxe et règles des formules pour les calculs personnalisés