customReportValues

Adaptive Planning

customReportValues

Actualizado en API v37.

Categoría	Recuperación de datos
Descripción	Devuelve un conjunto de datos para los criterios de informe solicitados en la instancia solicitada.
Permisos obligatorios para invocar	Ninguno (el usuario debe tener asignado un conjunto de permisos)
Parámetros obligatorios bajo petición	Credenciales, Informe

Para la versión 15 y posteriores de la API, llame a exportTime para recuperar los IDs de elemento de periodo correctos.

Consulte Referencia: condiciones de rendimiento de customReportValues para saber cómo garantizar que sus solicitudes aprovechen las mejoras de rendimiento y escalabilidad publicadas en 2023R2 para API v36.

La solicitud de este método contiene una especificación para un informe que se puede usar para buscar datos y devolver valores. La API acepta números de ID internos como entradas. Se puede llamar a las API de recuperación de metadatos para obtener IDs válidos. Los resultados se representan mediante coordenadas y valores. La respuesta también devuelve avisos y mensajes de error, si procede.

Esta API se basa en los informes de matriz. La solicitud requiere que la persona que llama especifique elementos en un eje X (columnas), un eje Y (filas) y en un eje de filtro opcional que se utiliza para filtrar todos los datos recuperados por la API. Los informes de matriz contienen ejes que determinan qué datos aparecen en el informe. Cada eje define un borde del informe. Todos los informes de matriz tienen tres ejes:

el eje X (el borde superior). Define el conjunto de columnas del informe.

el eje Y (el borde izquierdo). Define el conjunto de filas de un informe

el eje de filtro, un eje global que define las propiedades que se aplican a todos los datos del informe. Consulte los ejemplos de eje de filtro para obtener más información.

Un eje se puede dividir en varios segmentos. Un segmento es una forma de separar conjuntos de dimensiones en un solo eje. El eje de filtro solo puede tener un segmento, pero los otros dos ejes pueden tener tantos segmentos como desee.

Cada segmento puede tener un número ilimitado de niveles. Un nivel representa una dimensión lógica única que se utiliza para describir qué elementos de esa dimensión se aplican a las filas o columnas que se encuentran debajo de ella. Un segmento solo puede contener como máximo un nivel por dimensión lógica.

Cada nivel puede contener uno o varios elementos de la dimensión del nivel. (Todos los elementos del nivel deben pertenecer a la dimensión especificada en el nivel). Un elemento suele ser un ítem de la dimensión, como una cuenta concreta en la dimensión de cuenta o un trimestre contable en la dimensión de tiempo. A continuación, el sistema utiliza estos elementos para seleccionar y agregar los datos que se encuentran en el informe.

Cuando un segmento en el eje X o Y contiene varios niveles, los elementos de cada nivel se combinan con todos los elementos de todos los demás niveles para formar el producto cartesiano de todas las combinaciones posibles de elementos de nivel. Cada columna o fila representa una posible combinación de elementos, seleccionando un elemento de cada nivel. Por ejemplo, si un segmento en el eje X (las columnas de la parte superior) contiene un nivel con cinco elementos y un segundo nivel con dos elementos, el segmento dará como resultado diez columnas independientes, que representarán todas las combinaciones posibles de los elementos en los niveles No puede colocar un tipo de elemento en varios ejes. Por ejemplo, si coloca el tipo de elemento de cuenta en filas, no podrá añadir cuentas en columnas ni filtros.

Un nivel puede tener tanto elementos individuales como elementos de agrupación. Los elementos de agrupación agrupan arbitrariamente todos los elementos especificados debajo de ellos. Los elementos de agrupación no están permitidos en el filtro.

El eje de filtro se comporta de manera muy similar a los ejes X e Y, pero tiene una pequeña diferencia: dado que el eje de filtro se aplica a todos los datos del informe, no puede combinar sus niveles para formar varias filas o columnas. En su lugar, el eje de filtro combina todos los elementos de cada nivel, agregando los datos de todos los elementos como si esos elementos se estuvieran agrupando en una sola agregación.

Consulte Creación de informes de matriz básicos para obtener más información sobre segmentos, ejes y elementos dimensionales.

Ejemplos de eje de filtro

El siguiente ejemplo muestra todos los elementos posibles para el eje de 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 de solicitud

El esquema XML de la solicitud se puede encontrar aquí: 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>

Cada invocación de esta llamada API debe contener exactamente un elemento de cada uno de los tipos enumerados:

credenciales

informe

elemento de credenciales
Nombre de etiqueta		credenciales
Descripción		Todas las llamadas a la API deben contener un único elemento de credenciales para identificar al usuario que invoca la API. A continuación, la llamada a la API se realiza como este usuario (cualquier pista de auditoría o historial de acciones en el sistema mostrará que este usuario ha realizado la acción) y, por lo tanto, el usuario debe tener los permisos necesarios para realizar la acción a fin de que la llamada a la API se lleve a cabo. correcta
Atributos del elemento
Nombre de atributo	¿Obligatorio?	Valor	Ejemplo
inicio de sesión	Sí	El nombre de conexión del usuario que invoca el método API. Este usuario debe tener los permisos necesarios para invocar el método.	sampleuser@company.com
contraseña	Sí	La contraseña del usuario que invoca el método API.	my_password
configuración regional	No	Especifique la configuración regional que se utilizará para interpretar los números y las fechas de entrada, y para dar formato a los números y las fechas de salida (utilizando el separador de miles, los nombres de mes y el formato de fecha adecuados). La configuración regional también se utiliza para especificar el idioma en el que deben aparecer los mensajes del sistema en la respuesta. Si no se especifica, se utiliza en_US (inglés americano).	fr_FR
instanceCode	No	Si el usuario especificado en las credenciales tiene acceso a más de una instancia de Adaptive Planning , este atributo se puede utilizar para especificar que el usuario tiene la intención de acceder a una instancia distinta a la instancia por defecto. Si no se especifica, se utilizará la instancia por defecto del usuario. Para determinar los códigos de instancia disponibles, utilice la API exportInstances.	MYINSTANCE1
Contenido del elemento
(ninguno)

elemento de informe

Nombre de etiqueta

informe

Descripción

Especifica los elementos que componen el informe.

Atributos del elemento

Nombre de atributo

¿Obligatorio?

Valor

Ejemplo

suprimir ceros

Actualizado en API v37.

Este atributo rige la supresión en el nivel de fila. Al especificar esto, se controlará si el resultado contiene cero filas o filas en blanco o no. Los valores válidos son 0 (Suprimir nada - Mostrar todas las filas), 1 (Suprimir espacios en blanco - Suprimir filas que solo contengan celdas en blanco) y 2 (Suprimir espacios en blanco y cero - Suprimir filas que solo contengan celdas en blanco o cero). Si no se especifica este atributo, el valor por defecto es 2. Una celda se considera en blanco si el valor del explorador de celdas para esa celda está vacío.

Este atributo funciona junto con el atributo "cell-inclusions". Consulte "inclusiones de celda" para comprobar el comportamiento por defecto.

inclusiones-celda

Disponible en API v37.

Este atributo rige la supresión a nivel de celda para todas las filas no suprimidas según lo dictado por el atributo "suppress-zeroes". Al especificar esto, se controlará si el resultado contiene cero celdas o celdas en blanco o no. Los valores válidos son 0 (Incluir todo - mostrar todas las celdas), 1 (Incluir datos y cero - Excluir celdas en blanco) y 2 (Incluir solo datos - Excluir cero y celdas en blanco).

Comportamiento por defecto: si no se especifica este atributo, el comportamiento por defecto lo determina el atributo "suppress-zeroes". Comportamiento para distintos valores de atributo "suppress-zeroes":

"suppress-zeroes"	"comportamiento de inclusión de celda (valor)
0	Incluir todas las celdas (0)
1	Incluir datos y cero celdas (1)
2	Incluir solo celdas de datos (2)

show-cell-notes

Cuando se proporciona, este atributo muestra u oculta las notas de celda. 0=No mostrar notas de celda (por defecto), 1=mostrar notas de celda

suprimir agrupaciones

Cuando se proporciona, este atributo muestra u oculta las filas y columnas de agrupación. Las filas y columnas de agrupación solo se suprimen para aquellos elementos principales cuyos elementos secundarios están presentes en el informe. Los valores válidos son 0 (no suprimir agrupaciones) o 1 (suprimir agrupaciones). El valor por defecto es 0.

include-element-code

Cuando se proporciona, este atributo añade u oculta los códigos de los elementos Calc (Subtotal, Difference y Calculation). Los valores válidos son 0 (no añadir códigos a la salida de elementos de cálculo) o 1 (añadir códigos a la salida de elementos de cálculo). El valor por defecto es 0.

Contenido del elemento

Consulte el Formato de solicitud para obtener más detalles.

Formato de respuesta

El esquema XML de la respuesta se puede encontrar en 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 de respuesta
Nombre de etiqueta		respuesta
Atributos del elemento
Nombre de atributo	¿Obligatorio?	Valor	Ejemplo
éxito	Sí	Verdadero o falso, que indica si la llamada a la API se ha realizado correctamente o no. Incluso las llamadas correctas pueden contener mensajes de aviso en su respuesta.	verdadero
obsoleto	No	Si está presente en la etiqueta de respuesta y se establece en verdadero, este atributo indica que la versión del método o API que se está invocando ha quedado obsoleta y está oficialmente desaprobada. Aunque sigue funcionando en este momento, es posible que deje de funcionar en un breve periodo de tiempo. Normalmente, este atributo no está presente.	falso
Contenido del elemento
Un único elemento de mensajes opcional y exactamente un elemento de resultado obligatorio.

elemento de mensajes
Nombre de etiqueta	mensajes
Descripción	Contenedor para uno o varios elementos de mensaje.
Atributos del elemento
(ninguno)
Contenido del elemento
Uno o varios elementos de mensaje

elemento de mensaje
Nombre de etiqueta		mensaje
Descripción		Representa un mensaje que se envía desde el sistema a la persona que llama. Los mensajes se utilizan para los mensajes de error cuando las solicitudes no se realizan correctamente, para los mensajes de aviso cuando las solicitudes se realizan correctamente y para los mensajes de confirmación cuando se realizan correctamente.
Atributos del elemento
Nombre de atributo	¿ Obligatorio ?	Valor	Ejemplo
tipo	Sí	Tipo es una forma de identificar el tipo de mensaje. Los distintos tipos son INFO, WARNING y ERROR. El tipo "ERROR" significa que esta solicitud no se ha procesado.	AVISO
clave	Sí	Una clave es una forma de identificar un mensaje o tipo de mensaje en particular, útil para el registro de errores automatizado y la recuperación en los programas cliente. Las claves no cambian en las distintas configuraciones regionales de las solicitudes, aunque cambie el idioma del mensaje. Tampoco es probable que las claves cambien en el futuro debido a ajustes de redacción o cambios de terminología.	Warning-Invalid-Time-Span-Start
valores	No	Cuando se proporcionan, los valores representan variables que se utilizan en el texto del mensaje.	199,12
Contenido del elemento
El texto del mensaje. Este texto está en el idioma de la configuración regional especificada en la solicitud (suponiendo que la configuración regional sea compatible). El texto también puede contener información variable, como el número de filas que se han procesado o la columna o el valor concretos que han provocado el error.

elemento de resultado
Nombre de etiqueta	salida
Descripción
Atributos del elemento
(ninguno)
Contenido del elemento
Consulte el XML de respuesta para obtener más detalles.

Consulte Concepto: sintaxis y reglas de fórmulas para cálculos personalizados