diff --git a/functionalities-guide/Manuals/BigDataManual.es.rst b/functionalities-guide/Manuals/BigDataManual.es.rst new file mode 100644 index 00000000..31eb1b8e --- /dev/null +++ b/functionalities-guide/Manuals/BigDataManual.es.rst @@ -0,0 +1,20 @@ +.. incluír::.. /bookStructures/ka_BooksStructureForBigData.rst +.. incluír::.. /Misdatos/ka_user_my_data.rst +.. incluír::.. /Dataset/ka_dev_dataset.rst +.. incluír::.. /BehavioralModel/ka_dev_behavioralmodel.rst +.. incluír::.. /AnalyticalDocument/ka_dev_analyticaldoc.rst +.. incluír::.. /Gráfico/ka_user_chart.rst +.. incluír::.. /Gráfico/ka_dev_chart.rst +.. incluír::.. /Cockpit/ka_user_cockpit.rst +.. incluír::.. /QbeMeta/ka_dev_introqbemeta.rst +.. incluír::.. /FreeInquiry/ka_user_freeinquiry.rst +.. incluír::.. /MetaWeb/ka_dev_metaweb.rst +.. incluír::.. /Informes/ka_user_reporting.rst +.. incluír::.. /Informes/ka_dev_reporting.rst +.. incluír::.. /Jasper/ka_dev_jasper.rst +.. incluír::.. /LocationIntelligence/ka_dev_introlocationintelligence.rst +.. incluír::.. /LocationIntelligence/ka_user_locationintelligence.rst +.. incluír::.. /LocationIntelligence/ka_dev_locationintelligence.rst +.. incluír::.. /Datamining/ka_user_datamining.rst +.. incluír::.. /Datamining/ka_dev_datamining.rst +.. incluír::.. /Red/ka_dev_network.rst diff --git a/functionalities-guide/Manuals/EnterpriseReportingManual.es.rst b/functionalities-guide/Manuals/EnterpriseReportingManual.es.rst new file mode 100644 index 00000000..55ba2eb6 --- /dev/null +++ b/functionalities-guide/Manuals/EnterpriseReportingManual.es.rst @@ -0,0 +1,8 @@ +.. incluír::.. /bookStructures/ka_booksStructureForEnterpriseReporting.rst +.. incluír::.. /Misdatos/ka_user_my_data.rst +.. incluír::.. /Dataset/ka_dev_dataset.rst +.. incluír::.. /BehavioralModel/ka_dev_behavioralmodel.rst +.. incluír::.. /AnalyticalDocument/ka_dev_analyticaldoc.rst +.. incluír::.. /Informes/ka_user_reporting.rst +.. incluír::.. /Informes/ka_dev_reporting.rst +.. incluír::.. /Jasper/ka_dev_jasper.rst diff --git a/functionalities-guide/Manuals/ManualLocationInteligence.es.rst b/functionalities-guide/Manuals/ManualLocationInteligence.es.rst new file mode 100644 index 00000000..37a7a650 --- /dev/null +++ b/functionalities-guide/Manuals/ManualLocationInteligence.es.rst @@ -0,0 +1,12 @@ +.. incluír::.. /bookStructures/ka_booksStructureForLocationInteligence.rst +.. incluír::.. /Misdatos/ka_user_my_data.rst +.. incluír::.. /Dataset/ka_dev_dataset.rst +.. incluír::.. /BehavioralModel/ka_dev_behavioralmodel.rst +.. incluír::.. /AnalyticalDocument/ka_dev_analyticaldoc.rst +.. incluír::.. /QbeMeta/ka_dev_introqbemeta.rst +.. incluír::.. /FreeInquiry/ka_user_freeinquiry.rst +.. incluír::.. /LocationIntelligence/ka_dev_introlocationintelligence.rst +.. incluír::.. /LocationIntelligence/ka_user_locationintelligence.rst +.. incluír::.. /LocationIntelligence/ka_dev_locationintelligence.rst +.. incluír::.. /SVG/ka_user_svg.rst +.. incluír::.. /SVG/ka_dev_svg.rst diff --git a/functionalities-guide/Manuals/PerformanceManagement.es.rst b/functionalities-guide/Manuals/PerformanceManagement.es.rst new file mode 100644 index 00000000..37d8499b --- /dev/null +++ b/functionalities-guide/Manuals/PerformanceManagement.es.rst @@ -0,0 +1,9 @@ +.. incluír::.. /bookStructures/bookStructureForPerformanceManagement.rst +.. incluír::.. /Misdatos/ka_user_my_data.rst +.. incluír::.. /Dataset/ka_dev_dataset.rst +.. incluír::.. /BehavioralModel/ka_dev_behavioralmodel.rst +.. incluír::.. /AnalyticalDocument/ka_dev_analyticaldoc.rst +.. incluír::.. /Gráfico/ka_dev_chart.rst +.. incluír::.. /KPI/ka_KPI.rst +.. incluír::.. /ScoreCard/ka_Scorecard.rst +.. incluír::.. /Alerta/ka_Alert.rst diff --git a/functionalities-guide/Manuals/PredictiveAnalysisManual.es.rst b/functionalities-guide/Manuals/PredictiveAnalysisManual.es.rst new file mode 100644 index 00000000..444e46bc --- /dev/null +++ b/functionalities-guide/Manuals/PredictiveAnalysisManual.es.rst @@ -0,0 +1,11 @@ +.. incluír::.. /booksStructure/booksStructureForPredictiveAnalysis.rst +.. incluír::.. /Misdatos/ka_user_my_data.rst +.. incluír::.. /Dataset/ka_dev_dataset.rst +.. incluír::.. /BehavioralModel/ka_dev_behavioralmodel.rst +.. incluír::.. /AnalyticalDocument/ka_dev_analyticaldoc.rst +.. incluír::.. /Datamining/ka_user_datamining.rst +.. incluír::.. /Datamining/ka_dev_datamining.rst +.. incluír::.. /OLAP/ka_user_OLAP.rst +.. incluír::.. /OLAP/ka_dev_OLAP.rst +.. incluír::.. /WhatIf/ka_user_whatif.rst +.. incluír::.. /WhatIf/ka_dev_whatif.rst diff --git a/functionalities-guide/Manuals/SmartIntelligence.es.rst b/functionalities-guide/Manuals/SmartIntelligence.es.rst new file mode 100644 index 00000000..1c0c116a --- /dev/null +++ b/functionalities-guide/Manuals/SmartIntelligence.es.rst @@ -0,0 +1,21 @@ +.. incluír::.. /booksStructures/booksStructureForSmartIntelligence.rst +.. incluír::.. /Misdatos/ka_user_my_data.rst +.. incluír::.. /Dataset/ka_dev_dataset.rst +.. incluír::.. /BehavioralModel/ka_dev_behavioralmodel.rst +.. incluír::.. /AnalyticalDocument/ka_dev_analyticaldoc.rst +.. incluír::.. /Gráfico/ka_user_chart.rst +.. incluír::.. /Gráfico/ka_dev_chart.rst +.. incluír::.. /Cockpit/ka_user_cockpit.rst +.. incluír::.. /QbeMeta/ka_dev_introqbemeta.rst +.. incluír::.. /FreeInquiry/ka_user_freeinquiry.rst +.. incluír::.. /MetaWeb/ka_dev_metaweb.rst +.. incluír::.. /SmartFilter/ka_user_smartfilter.rst +.. incluír::.. /SmartFilter/ka_dev_smartfilter.rst +.. incluír::.. /Registro/ka_user_registry.rst +.. incluír::.. /Registro/ka_dev_registry.rst +.. incluír::.. /Informes/ka_user_reporting.rst +.. incluír::.. /Informes/ka_dev_reporting.rst +.. incluír::.. /Jasper/ka_dev_jasper.rst +.. incluír::.. /OLAP/ka_user_OLAP.rst +.. incluír::.. /OLAP/ka_dev_OLAP.rst +.. incluír::.. /Glosario/ka_dev_glossary.rst diff --git a/functionalities-guide/advanced-data-access/index.es.rst b/functionalities-guide/advanced-data-access/index.es.rst new file mode 100644 index 00000000..3624617c --- /dev/null +++ b/functionalities-guide/advanced-data-access/index.es.rst @@ -0,0 +1,774 @@ +# Acceso avanzado a datos + +En esta sección suponemos que debemos iniciar sesión como usuario administrador. En este caso, la definición del conjunto de datos ya no está disponible en **Mis datos** sección. De lo contrario, la funcionalidad es otorgada por el **Conjunto de datos** punto bajo el **Proveedores de datos** del menú del servidor, como se destaca en la figura siguiente. Esta área le ofrece la posibilidad de definir conjuntos de datos entre una amplia gama de tipos. Además, puede agregar parámetros, definir el alcance, administrar metadatos y realizar operaciones avanzadas en conjuntos de datos. Mientras que la creación y gestión de conjuntos de datos entre el usuario y el administrador cambian a favor de este último, el **Modelos** y **Definiciones de federación** fichas disponibles en **Mis datos** la sección sigue siendo idéntica. Por esta razón, en este capítulo vamos a describir solo la creación y administración de conjuntos de datos. + +## Mi primer conjunto de datos + +Como se indicó anteriormente, puede abrir el editor gráfico del conjunto de datos seleccionando **Conjunto de datos** en **Proveedor de datos** , como se muestra a continuación. + +.. figura:: media/image20.png + + Access data set creation area. + +Un conjunto de datos actúa como un proveedor de datos para documentos analíticos, por lo que se admiten muchos tipos. Knowage administra varios tipos de conjuntos de datos: + +* Archivo +* Consulta +* Clase Java, +* Script (Groovy, JavaScript, Embedded JavaScript o ECMAScript), +* Consulta Qbe sobre el metamodelo, +* Costumbre +* Plano +* Ckan, +* Federado +* REPOSO +* Big Data, +* Solr +* Python/R. + +Todos los tipos de conjuntos de datos comparten algunas operaciones comunes, mientras que otros son específicos de cada uno de ellos. El proceso para definir un conjunto de datos dentro de Knowage es el siguiente: + +1. elegir un nombre y una etiqueta única; +2. elegir el tipo de conjunto de datos y el origen, en función del tipo de conjunto de datos; +3. escribir el código que define el conjunto de datos; +4. asociar parámetros al conjunto de datos, si los hubiera (opcional); +5. aplicar transformaciones (opcional); +6. pruebe el conjunto de datos y guárdelo. + +Algunos de estos pasos dependen del tipo específico de conjunto de datos, como veremos. + +Creación de nuevos conjuntos de datos + +``` + +The dataset graphical editor is divided into two areas: the left side shows the list of all available datasets and the right one shows three tabs, each one corresponding to a specific type of editing operation on dataset. + +Each item of the list in the left panel shows the dataset label (i.e., the dataset unique identifier), name and type, as well as the number of documents currently using it. To create a new dataset, click the **Add** icon |image14|. If your dataset is similar to another existing dataset, you can click the **Clone** icon |image16|. This will create a copy of the dataset, except for the label that must edit once again. All fields are pre-filled with values from the existing dataset but they can be modified and saved without affecting the original dataset. + +.. |image14| image:: media/image21.png + :width: 30 + +.. |image16| image:: media/image23.png + :width: 30 + +To remove an existing dataset, click the small dustbin icon |image17| on the corresponding row of the dataset list. + +.. |image17| image:: media/image24.png + :width: 30 + +Once you have clicked the **Add** button, you can fill in the dataset definition form. Each tab in the right panel corresponds to a step of the dataset definition process. + +In the **Detail** tab you define the Name, the Label and an optional Description of the dataset (refer to figure below). There is also a new feature, data set tags. These tags are used for filtering list of data sets and they are placed in the upper left corner of data set catalogue above list of data sets as you can see in the figure below. + +.. _datasetpanel: +.. figure:: media/image22.png + + Dataset Panel. + +By clicking on some of the tags, user is filtering data set list to show only data sets with that tag. In the detail part of data set, user can define tag for that data set by writing the name of the tag in the input field Tags. By clicking on Save button, user saves the new tag and he can see it in the data set tags list. + +In the lower part you can see a versioning system for the dataset: Knowage supports dataset versioning, as shown in figure below, therefore, each time you edit and save a dataset, the older version is archived and is still accessible from the lower part of the detail panel. + +.. _datasetversioning: +.. figure:: media/image25.png + + The dataset versioning. + +The Scope lets you choose between two options, whose combination allows the definition of fine-grained purpose datasets. In Table below all details of possible matching are provided. + +.. table:: Scope options + :widths: auto + + +-----------------------+-----------------------+-----------------------+ + | Dataset | Private | Public | + +=======================+=======================+=======================+ + | User | Created from file | Dataset created from | + | | (CSV, XLS) or from | file (CSV, XLS) or | + | | QbE (My Data) for | from QbE (My Data) | + | | personal use only. | and shared with other | + | | | users. | + +-----------------------+-----------------------+-----------------------+ + | Technical | Not applicable. | Dataset created by a | + | | | BI developer to be | + | | | used in one or more | + | | | documents. | + | | | | + | | | Not visible to end | + | | | users. | + +-----------------------+-----------------------+-----------------------+ + | Enterprise | Not applicable. | Dataset of any type | + | | | created by a | + | | | technical user and | + | | | certified by a | + | | | trusted entity within | + | | | the organization, and | + | | | made available to all | + | | | end users for reuse. | + +-----------------------+-----------------------+-----------------------+ + +You can also specify the Category of the dataset. This field is not mandatory but it can be used to categorize datasets in your BI project, so that you can easily recover them when performing searches. + +In the **Type** tab you can define the type of dataset: here you have to write the code or upload an XLS file or call for a web service accordingly to the dataset type and add parameters to it, if any. An example is shown below. + +.. figure:: media/image26.png + + The dataset type definition. + +In the **Advanced** tab, shown in figure below, you can apply the pivoting transformation to the dataset results if needed or decide to persist the dataset. + +.. figure:: media/image27.png + + The dataset transformation tab. + +Once all those settings have been performed you can see a preview of the dataset results clicking on the **Preview** button available on the top right corner of the page. It is recommended to check preview to detect possible errors in the dataset code before associating it to a document. + +Note that the metadata can be manage by clicking on the icon |image21| and use the same criterion described in Dataset paragraph. Otherwise use the icon |image211| to save without associating any metadata. + +.. |image21| image:: media/image28.png + :width: 30 + +.. |image211| image:: media/image29.png + :width: 30 + +Let us describe more deeply each type of dataset. + +File Dataset +~~~~~~~~~~~~ + +A dataset of type File, see the following figure, reads data from an XLS or CSV file. To define a **File Dataset** select the File type, then upload the file by browsing in your personal folders and set the proper options for parsing it. + +.. figure:: media/image30.png + + File Dataset. + +Once you have uploaded the file, you can check and define the metadata (measure or attribute) of each column. + +Query Dataset +~~~~~~~~~~~~~ + +Selecting the query option requires the BI developer to write an SQL statement to retrieve data. + +The SQL dialect depends on the chosen data source. The SQL text must be written in the Query text area. Look at SQL query example. + +.. code-block:: sql + :caption: SQL query example + :linenos: + + SELECT p.media_type as MEDIA, sum(s.store_sales) as SALES + FROM sales_fact_1998 s + JOIN promotion p on s.promotion_id=p.promotion_id + GROUP BY p.media_type + +It is also possible to dynamically change the original text of the query at runtime. This can be done by defining a script (Groovy or JavaScript) and associating it to the query. Click on the **Edit Script** button (see next figure) and the script editor will open. Here you can write the script. The base query is bounded to the execution context of the script (variable query) together with its parameters (variable parameters) and all the profile attributes of the user that executes the dataset (variable attributes). + +.. _scripteditingdataset: +.. figure:: media/image31.png + + Script editing for dataset. + +In Code Query dataset’s script example we uses JavaScript to dynamically modify the ``FROM`` clause of the original query according to the value of the parameter year selected at runtime by the user. + +.. code-block:: javascript + :caption: Query dataset’s script example + :linenos: + + if( parameters.get('year') == 1997 ) { query = query.replace(FROM + sales_fact_1998, FROM sales_fact_1997); + } else { query = query; // do nothing + } + +Java Class Dataset +~~~~~~~~~~~~~~~~~~ + +Selecting a dataset of **Java Class** type allows the execution of complex data elaboration implemented by a Java class. The compiled class must be available at \\webapps\\ Knowage\WEB-INF\\ classes with the proper package. The class defined by the developer must implement the interface it.eng.spagobi.tools.dataset.bo.IJavaClassDataSet and the methods implemented are: + +- ``public String getValues(Map profile, Map parameters)``. This method provides the result set of the dataset using profile attributes and parameters. The String to return must be the XML result set representation of type: + +.. code-block:: xml + :linenos: + + + + + + +- ``public List getNamesOfProfileAttributeRequired()``. This method provides the names of profile attributes used by this dataset implementation class. This is a utility method, used during dataset execution. + +Script +~~~~~~ + +If you select this option, the results of the dataset will be produced by a script. Therefore, the developer should write a script returning an XML string containing a list of values with the syntax shown below. + +.. code-block:: xml + :linenos: + + + + + + +If the script returns a single value, this will be automatically encoded in the XML format above. The script must be written using Groovy or Javascript language. Knowage already provides some Groovy and JavaScript functions returning the value of a single or multi-value profile attribute. These functions are explained in the information window that can be opened from the **Dataset Type** tab. New custom functions can be added in ``predefinedGroovyScript.groovy`` and ``predefinedJavascript.js`` files contained in the ``KnowageUtils.jar`` file. + +QbE +~~~ + +.. important:: + **Enterprise Edition** + + If you purchased Knowage EE, this feature is available only in KnowageBD and KnowageSI + +The QbE dataset type option allows the definition of dataset results based on a query defined over a metamodel. To define a QbE dataset you need to select the Data Source and Datamart that you want to use. Once chosen your datamart you can click the lookup button of the Open QbE field and a pop up window will appear showing a QbE interface where you can define your query. Once saved, you can check the generated query thanks to the View QbE Query. + +All these features are exhibited below. + +.. figure:: media/image32.png + + QbE Dataset. + +Custom Dataset +~~~~~~~~~~~~~~ + +Selecting a Custom dataset type allows the developer to execute complex data elaboration by a custom Java dataset implementation. There are two options: + + - implement the ``it.eng.spagobi.tools.dataset.bo.IDataSet`` interface; + - extend the ``it.eng.spagobi.tools.dataset.bo.AbstractCustomDataSet`` class. + +The methods executing the dataset that must be implemented are: + + - ``void loadData()``; + - ``void loadData(int offset, int fetchSize, int maxResults)``; + +Using the ``AbstractCustomDataset`` class allows the developer to access predefined utility methods, such as: + + - ``public void setParamsMap(Map paramsMap)``; + - ``public IDataSetTableDescriptor createTemporaryTable (String tableName, Connection connection)``; + - ``public IDataStore decode(IDataStore datastore)``; + - ``private void substituteCodeWithDescriptions(IDataStore datastore, Map> codes, Map> descriptions)``; + - ``private Map> getCodes(IDataStore datastore)``. + +The full class name (package included) must be set on the Java class name field, while it is possible to add custom attributes for dataset execution and retrieve them via the following method of the ``IDataSet`` interface: ``Map getProperties()``. + +Flat Dataset +^^^^^^^^^^^^ + +A flat dataset allows the retrieval of an entire table from a data source. In other words, it replaces a dummy query like ``select * from sales`` by automatically retrieving all rows in a table. To create a flat dataset, simply enter the table and the data source name, as shown below. + +.. figure:: media/image33.png + + Flat Dataset. + +Ckan +^^^^ + +.. important:: + **Enterprise Edition** + + If you purchased Knowage EE, this feature is available only in KnowageBD and KnowageSI + +A Ckan dataset let you use open data as resource. You have to fill all the settings fields properly to let the dataset work successfully. Let’s have a look on them: + + - **File Type**: this field specifies the type of the file you want to import. Allowed ones are: CSV or XML; + - **Delimiter Character**: Here you have to insert the delimiter used in the file. Allowed values are: , ; \\t \| + - **Quote Character**: Allowed values for this field are: “ or ”; + - **Encoding**: Here you have to specify the encoding typology used. Allowed values are: UTF-8, UTF-16, windows-1252 , ASCII or ISO-8859-1; + - **Skip rows**: the number inserted stands for the rows not to be imported; + - **Limit rows**: it is the maximum number of rows to be imported. If you leave it blank all rows are uploaded; + - **XLS numbers**: it is the number of sheets to be imported; + - **CKAN ID** : here you have to insert the ID of the resource you are interested in. Look for it among the additional information in Ckan dataset webpage. + - **CKAN url**: it is the direct link to download the resources available on Ckan dataset webpage. + +We marked with the \* symbol the mandatory fields. We suggest to do a preview of your dataset before saving it to be sure everything have been correctly configured. + +Federated +^^^^^^^^^ + +.. important:: + **Enterprise Edition** + + If you purchased Knowage EE, this feature is available only in KnowageBD and KnowageSI + +In this area you can only manage metadata, visibility and perform the advanced operation we are going to describe at the end of this section. + +Instead, the creation of **Federated** done can be accessed from **My data** BI functionality under **Federatation Definitions**. + +Rest +^^^^ + +The REST dataset enables Knowage to retrieve data from external REST services. The developer of the dataset is free to define the body, method, headers and parameters of the request; then he has to specify how to read data from the service response using JSON Path expressions (at the moment no other ways to read data is available, therefore the REST service is presumed to return data in JSON format). + +Let’s make as example in order to understand how it works. Suppose an external REST service providing data from sensors, we want to retrieve values from prosumers electricity meters, a prosumer being a producer/consumer of electricity, and that the request body should be something like: + +.. code-block:: json + :caption: Request body code + :linenos: + + { "entities": [ { + "isPattern": "true", + "id": ".*", + "type":"Meter" + } ] + } + +while querying for ``Meter`` entities, and that the JSON response is something like: + +.. code-block:: json + :caption: RJSON response code + :linenos: + + { + "contextResponses": [ + { + "contextElement": { + "id": "pros6_Meter", + "type": "Meter", + "isPattern": "false", + "attributes": [ + { + "name": "atTime", + "type": "timestamp", + "value": "2015-07-21T14:49:46.968+0200" + }, + { + "name": "downstreamActivePower", + "type": "double", + "value": "3.8" + }, + { + "name": "prosumerId", + "type": "string", + "value": "pros3" + }, + { + "name": "unitOfMeasurement", + "type": "string", + "value": "kW" + }, + { + "name": "upstreamActivePower", + "type": "double", + "value": "3.97" + } + ] + }, + "statusCode": { + "reasonPhrase": "OK", + "code": "200" + } + }, + { + "contextElement": { + "id": "pros5_Meter", + "type": "Meter", + "isPattern": "false", + "attributes": [ + { + "name": "atTime", + "type": "timestamp", + "value": "2015-08-09T20:29:45.698+0200" + }, + { + "name": "downstreamActivePower", + "type": "double", + "value": "1.8" + }, + { + "name": "prosumerId", + "type": "string", + "value": "pros5" + }, + { + "name": "unitOfMeasurement", + "type": "string", + "value": "kW" + }, + { + "name": "upstreamActivePower", + "type": "double", + "value": "0" + } + ] + }, + "statusCode": { + "reasonPhrase": "OK", + "code": "200" + } + } + ] + } + +In this example we have two **Context Elements** with the following attributes: + + - **atTime** ; + - **downstreamActivePower**; + - **prosumerId**; + - **unitOfMeasurement**; + - **upstreamActivePower**. + + +Let’s see how to define a Knowage dataset: + +.. figure:: media/image34.png + + REST dataset interface. + +We specified + +- the URL of the REST service; +- the request body; +- the request headers (in this example we ask the service for JSON data); +- the HTTP method; +- the JSONPath to retrieve the items (see below), i.e. the JSONPath where the items are stored; +- the JSONPaths to retrieve the attributes (see below), i.e. the JSONPaths useful to retrieve the attributes of the items we are looking for; those paths are relative to the "JSON Path items"; +- offset, fetch size and max results parameters, in case the REST service has pagination. + +Once followed the steps above the user obtains upstream/downstream active power for each prosumer. + +**NGSI checkbox** is specific for NGSI REST calls: it permits easy the job when querying the Orion Context Broker (`https://github.com/telefonicaid/fiware-orion) `__ and to omit some of the REST fields (since the JSON format from NGSI specifications is fixed): you don’t need to specify headers, JSONPath items, JSONPath attributes (all available attributes are fetched) and pagination parameters (offset and fetch size). + +When checking the **Use directly JSON attributes** checkbox, yon can skip the definition of the JSONPath attributes, since the JSON structure is presumed to be fixed as in the following example: + +.. code-block:: json + :caption: Use directly JSON attributes + :linenos: + + { + "contextResponses": [ + { + "prosumerId":"pros1", + "downstreamActivePower":3.1, + "upstreamActivePower":0.0 + },{ + "prosumerId":"pros2", + "downstreamActivePower":0.5, + "upstreamActivePower":2.4 + } + ] + } + + +Then it will be enough to define only the **JSON Path Items** and check **Use directly JSON Attributes** without defining the attributes; the attributes will be retrieved automatically from the JSON object. + +In the above examples, the JSON Path Items will be ``$.contextResponses[:sub:`\*`]`` and the dataset result will look like: + +.. table:: Dataset result + :widths: auto + + +---------------+-----------------------+---------------------+ + | prosumerId | downstreamActivePower | upstreamActivePower | + +===============+=======================+=====================+ + | pros1 | 3.1 | 0.0 | + +---------------+-----------------------+---------------------+ + | pros2 | 0.5 | 2.4 | + +---------------+-----------------------+---------------------+ + +The REST dataset permits usage of profile attributes and parameters using the same syntax as for other dataset types: ``$`` and ``$P``. You can use both of them as placeholders in every field: most likely you need to use them in REST service URL or on the request body. As an example, suppose you want to retrieve the value of just one prosumer that is specified by the ``prosumerId`` parameter, you have to set the request body as: + +.. code-block:: json + :caption: Request body for prosumerId parameter + :linenos: + + { + "entities":[ + { + "isPattern":"true", + "type":"Meter", + "id":"$P{prosumerId}" + } + ] + } + +Python/R +^^^^^^^^ + +The Python/R dataset enables users to create a dataset by writing a Python or R script that directly retrieves data. +The developer of the dataset is free to write code which has to produce a **dataframe** variable as output (for Python scripts we refer to pandas dataframes). This variable will contain data that Knowage will later convert into its own format. + +.. figure:: media/PythonDatasetConfigurator.png + + Python/R dataset interface. + +As shown in the picture in the field **Dataframe variable name** the developer has to specify the name of the variable in which the final output of the script is stored in the form of a dataframe. + +In the field **Python environment** the user can select a working environment among the available ones defined in the **Configuration Management** section. + +Inside the scripts it is possible to use parameters by the usual syntax *$P{}*. + +Big Data - NoSQL +^^^^^^^^^^^^^^^^ + +.. important:: + **Enterprise Edition** + + If you purchased Knowage EE, this feature is available only in KnowageBD and KnowagePM + +Knowage provides the possibility to define Big Data dataset as well as Big Data datasources. To set these kind of datasets the user just have to select the **Query** type and insert the code according to the dialect in use (that is accordingly to the datasource dialect). + +For example, let’s suppose we defined a Mongo datasource and want to create a dataset upon it. Therefore choose the "Query type" dataset and, as we revealed in advance, choose the correct language: in this case JS instead of SQL. The script must respect some convention, in particular: + +- the return value of the query must be assigned to a variable with + name ”query“. For example + +.. code-block:: javascript + :caption: Request body for prosumerId parameter + :linenos: + + var query = db.store.find(); + +- if the return value doesn’t come from a query, for example it's a js variable, than it must be assigned to a variable with name ``sbiDatasetfixedResult``. The result will be managed by Knowage accordingly to the type of the variable: + + - if it’s a primitive type the resulting dataset contains only a columns with name ``result`` and value equal to the value of the variable ``sbiDatasetfixedResult``; + + - if it’s an object, the resulting dataset contains a column for each property of the object. + + For example, if we consider the query + ``sbiDatasetfixedResult = {a:2, b:3}`` + the dataset is as shown in Table below. + +.. table:: Dataset output + :widths: auto + + +------+------+ + | a | b | + +======+======+ + | 2 | 3 | + +------+------+ + +- if it’s a list than the columns of the dataset are the union of the properties of all the objects contained in the list. + + For istance, let’s consider the query + ``sbiDatasetfixedResult = [{a:2, b:3},{a:2, c:3}]`` + the dataset is + +.. table:: Dataset output + :widths: auto + + +------+------+------+ + | a | b | c | + +======+======+======+ + | 2 | 3 | | + +------+------+------+ + | 2 | | 3 | + +------+------+------+ + + +The result of a query in MongoDB can assume different shapes: Cursor, Document, List, fix value. Knowage can manage automatically the result of the query. The algorithm to understand how to manage the result is very simple. + +- If in the query it finds the variable sbiDatasetfixedResult the result will be managed as described above. +- If in the query it finds a findOne the result will be managed as a single document. +- If in the query it finds an aggregate the result will be managed as an aggregation. +- In the ether cases the result will be managed as a Cursor. + + +It’s possible to force the behaviour. In particular the result stored in the variable query, will be managed: + +- as cursor if in the script exist a variable with value ``LIST_DOCUMENTS_QUERY``. Example: + +.. code-block:: javascript + :linenos: + + var retVal= "LIST_DOCUMENTS_QUERY“; + +- a document if in the script exist a variable with value ``SINGLE_DOCUMENT_QUERY``. Example: + +.. code-block:: javascript + :linenos: + + var retVal= "SINGLE_DOCUMENT_QUERY”; + + +Similar techniques can be applied to the other languages. We leave the reader to examine the dialect related to each Big Data datasource. + +.. note:: + **MongoDB Document size** + + Remember that MongoDB has a limit of maximum 16MB for the returned document (BSON), so pay attention to that when creating your dataset. For more information check this link: https://docs.mongodb.com/manual/reference/limits/ + + +Solr Dataset +^^^^^^^^^^^^^^^^ + +A dataset of type Solr, see the following figure, reads data from the popular Search Engine Solr. To define a **Solr Dataset** select the Solr type, then choose between Document or Facets type. + +.. figure:: media/image41.png + + Solr Dataset, Document type selected. + + The **Query** field is the Solr query using the Solr standard query syntax. + The **Collection** field is the **core**, in Solr, the term core is used to refer to a single index and associated transaction log and configuration files (including the solrconfig.xml and Schema files, among others). Your Solr installation can have multiple cores if needed, which allows you to index data with different structures in the same server, and maintain more control over how your data is presented to different audiences. In SolrCloud mode you will be more familiar with the term collection. Behind the scenes a collection consists of one or more cores. + +**Documents** + +According to the Solr official documentation, Solr’s basic unit of information is a document, which is a set of data that describes something. A recipe document would contain the ingredients, the instructions, the preparation time, the cooking time, the tools needed, and so on. A document about a person, for example, might contain the person’s name, biography, favorite color, and shoe size. A document about a book could contain the title, author, year of publication, number of pages, and so on. + +In the Solr universe, documents are composed of fields (these fields can be put into section **document field list**), which are more specific pieces of information. Shoe size could be a field. First name and last name could be fields. +If you have chosen the type "Documents", you can add the document fields to the list below called "Documents". + +**Request header**, if there is the need, it is possible to customize the request header of the post http request, adding optional parameters. + +.. figure:: media/image43.png + + Solr Dataset, Optional fields for filtering parameters. + + Solr dataset can also use Profile Attributes. + The syntax to include attributes into the dataset text is ``${attribute_name}``. Profile attributes can be single-value or multivalue. + +The **filter query parameter** is the Solr fq parameter and defines a query that can be used to restrict the superset of documents that can be returned, without influencing score. It can be very useful for speeding up complex queries, since the queries specified with fq are cached independently of the main query. +These parameters can be used in combo with **document parameters** using the P{} notation like the example picture shows. + + +**Fields Mapping** + +It is important to set field types correctly in order to use a Solr dataset without problems. +A field type defines the analysis that will occur on a field when documents are indexed or queries are sent to the index. + +A field type definition can include four types of information: + + The name of the field type (mandatory). + An implementation class name (mandatory). If the field type is a number and it has decimals it must be set as pdouble (not int or string!!). + If the field type is TextField, a description of the field analysis for the field type. + Field type properties - depending on the implementation class, some properties may be mandatory. + +Example: + +**Faceting** + +Faceting is the arrangement of search results into categories based on indexed terms. +If you choose Facets you can add the Facet Query. +This parameter allows you to specify an arbitrary query in the Lucene default syntax to generate a facet count. +The Facet Field is the facet.field parameter and identifies a field that should be treated as a facet. It iterates over each Term in the field and generate a facet count using that Term as the constraint. This parameter can be specified multiple times in a query to select multiple facet fields. +The Facet Prefix is the facet.prefix parameter limits the terms on which to facet to those starting with the given string prefix. This does not limit the query in any way, only the facets that would be returned in response to the query. + +.. figure:: media/image44.png + + + + +Parameters and profile attributes +-------------------------------------- + +All dataset types except **File** and **CKAN** allow you to add parameters. This means that results can be customized according to the value of one or more parameters at execution time. Parameters can be managed from the **Type** tab. Two operations are needed to add a parameter to the dataset: + +1. insert the parameter in the actual text of the dataset; +2. create the parameter in the parameters list below the editor area. + +The syntax to add a parameter in the dataset code text is ``$P{parameter_name}``. At dataset execution time, the parameter will be replaced by its actual value. + +.. warning:: + **Attention to parameters’ names!** + + If the dataset is used by a Knowage document, then the document parameters’ URL must match the parameter name set in the dataset **Type** tab, in order for the dataset to be passed correctly. + +Any parameter added to your dataset must be added to the parameters list, too. To add a parameter in the list, click the **Add** button. A new row will be created in the list: double click the name and edit the parameter values. There are three different types of parameters. For each of them the placeholder will be replaced according to a different pattern, as follows: + +- **String**: the parameter value will be surrounded with single quotes if not already present. +- **Number**: the parameter value is treated as a number, with no quotes; an exception is thrown if the value passed is not a number. +- **Raw**: the parameter value is treated as a string containing a set of values; single quotes are removed from the containing string, not from the single strings composing it. +- **Generic**: the parameter is simply passed as it is, with no further processing. + +In SQL query example with parameters an example is provided, where ``MediaType`` is a string parameter. + +.. code-block:: sql + :caption: SQL query example with parameters + :linenos: + + SELECT s.customer_id as CUSTOMER + , sum(s.store_sales) as SALES + , c.yearly_income as INCOME + , p.media_type as MEDIA + FROM sales_fact_1998 s, customer c, promotion p + WHERE + s.customer_id=c.customer_id and s.promotion_id=p.promotion_id and + p.media_type in ($P{MediaType}) + GROUP BY + s.customer_id, + c.yearly_income, + p.media_type + + +Datasets of type Query and Script can also use *profile attributes*. Differently from parameters, profile attributes do not need to be explicitly added to the parameter list since they have been defined elsewhere. Clicking the **Available Profile Attribute** button you can see all profile attributes defined in the behavioural model and choose the one(s) you wish to insert in the dataset query/script text, as shown below. + +.. figure:: media/image35.png + + Profile Attributes assignment. + +The syntax to include attributes into the dataset text is ``${attribute_name}``. Profile attributes can be single-value or multivalue. + +.. note:: + **User profile attributes** + + Each Knowage user is assigned a profile with attributes. The user profile is part of the more general behavioural model, which allows tailored visibility and permissions on Knowage documents and functionalities. + + +Further operations on a dataset +------------------------------------ + +Script option +~~~~~~~~~~~~~ + +As we reported in Section 'Query Dataset', the script option can be very useful when the user wants to create a very dynamic query. Dealing with parameters, if the query syntax is not handled properly, the missing of one parameter value may compromise the dataset execution itself. In particular, it can be convenient to use a script to manage the assignment of null or empty values to parameters in those cases when the user wants the filters not to be applied. + +Knowage query dataset are endowed of a specific area to insert the script syntax. Clicking on the "Script" button we reported in section Query Dataset', the interface opens a wizard containing two tabs: the script tab is the one opened by default. Here the user is asked to select the language he/she's intended to use. + +.. figure:: media/image039.png + + Editing script. + +Typically, scripts are configured to load placeholders with a slice of SQL code. Referring to the following pictures, we show an example of JavaScript (JS) code usage. Moving to the "Query" tab the user has to insert a placeholder where he/she's expecting a certain clause to be added. The query will then look like the one shown below. + +.. figure:: media/image038.png + + Setting placeholder using script. + +Moving to the "Script" tab instead, the user has to declare how the server has to manage the placeholder. The following picture shows a JS block code where the user first initializes a variable as empty: if certain conditions, on one or more parameters, are satisfied, the variable is assigned an SQL code string. Then, the JS method ".replace" will substitute the placeholder with the content the variable. + +.. figure:: media/image040.png + + Editing script. + +To sum up, the example reveals that if the parameter is assigned a null or empty value, conditions are not satisfied and the placeholder is substituted with an empty space (therefore nothing is added to the "where" clause). Otherwise, the SQL code is inserted into the "where" clause and the dataset is accordingly filtered. + +We stress that it is not necessary to use any concatenation or JS method to recall for parameters' values. It is enough to use the syntax $P{par_name} as well as seen when configuring a plain parametric dataset. + +Transformations +~~~~~~~~~~~~~~~ + +In some cases it is useful to perform transformations on the results of a dataset, to obtain data in the desired format. The most common operation is the pivot transformation, which allows the switch between rows and columns of the dataset results. Knowage supports this operation on any type of dataset. + +To set a pivot transformation, select **Pivot Transformer** in the drop down menu of the **Transformation** tab. Then set the following fields: + +- **Name of Category Column to be Pivoted**. Here you should write the name of the dataset column whose values will be mapped onto columns after pivoting. +- **Name of Value Column to be Pivoted**. Here you should write the name of the result set column, whose values should become values of the previous columns (category columns). +- **Name of the Column not to be Pivoted**. Here you should write the name of those columns that should not be altered during the transformation. +- In case you wish to add a number to category columns (e.g., 1_name_of_column), you should check the option **Automatic Columns numeration**. + +An example of usage is available in figure below, showing the result set of the dataset. + +.. figure:: media/36a.png + + Pivot transformation. + + +Dataset persistence +~~~~~~~~~~~~~~~~~~~ + +The **Advanced** tab is used to make a dataset persistent, i.e., to write it on the default database. Making a dataset persistent may be useful in case dataset calculation takes a considerable amount of time. Instead of recalculating the dataset each time the documents using it are executed, the dataset is calculated once and then retrieved from a table to improve performance. In order to force recalculation of the dataset, you should execute dataset preview again. This will store the newly generated data on the database table. + +Once marked the dataset as persistent, you are asked to insert a table name. This is the table where data are stored and then retrieved. + +.. important:: + **Enterprise Edition only** + + With KnowageBD, KnowageER and KnowageSI products you can also decide to schedule the persistence operation: this means that the data stored in the table will be update with according to the frequency defined in the **scheduling** options. Choose your scheduling option and save the dataset. Now the table where your data are stored will be persisted according to the settings provided. + +Preview +~~~~~~~ + +Before actually using the dataset in a document, it is a good practice to test it. Clicking the **Preview** button within the **Preview** tab, you can see a preview of the result set, see the following figure. This allows the developer to check any anomaly or possible error in the dataset definition, before using it. + +.. figure:: media/image37a.png + + Dataset preview (left) and parameters prompt window (right). + + +If some parameters have been set, a window with their list will be shown: their values must be entered by double clicking on the set to string, just write the value you want to assign in the preview: quotes will be added automatically. On the other hand, if the type is raw or generic but you want to input text, then remember to add quotes to the test value. +``` diff --git a/functionalities-guide/alert/index.es.rst b/functionalities-guide/alert/index.es.rst new file mode 100644 index 00000000..151feb01 --- /dev/null +++ b/functionalities-guide/alert/index.es.rst @@ -0,0 +1,48 @@ +# Alerta + +El **Alerta** funcionalidad disponible en el marco del **Herramienta** del menú principal de Knowage, como se muestra en la figura a continuación, le permite implementar un control sobre los eventos. Técnicamente consiste en monitorizar la posible superación de umbrales fijos y la consiguiente señal de anomalías mediante un correo electrónico o mediante el lanzamiento de un proceso ETL. En los siguientes apartados veremos en detalle cómo configurar las alarmas utilizando la función Alerta. + +.. \_alertfunctfrom: +.. figura:: media/image172.png + + Alert functionality from contextual menu. + +## Implementación de alertas + +La ventana definición de alerta (consulte la figura anterior) reproduce la lista de alertas existentes y un cuadro de búsqueda en la parte superior de la página para facilitar la navegación por los elementos. En la esquina superior derecha está disponible el icono "Plus" para configurar una nueva alerta. + +Al hacer clic en el icono "Más", se abre la página de la siguiente figura. + +.. figura:: media/image173.png + + Alert definition window. + +Asigne un nombre y seleccione la opción **Oyente de KPI** desde el cuadro combinado. A continuación, indique la fecha de inicio, la hora de inicio y, finalmente, la fecha de finalización de la implementación de alert. Especifique el intervalo de tiempo y cuántas veces debe repetirse. En este punto elige entre **Ejecución única** y **Evento antes de desencadenar acciones**: en el primer caso la alerta debe señalar la anomalía una sola vez que se produce, mientras que en el otro caso debe enviar las alarmas cuando se produce la irregularidad tantas veces como se especifique. Tenga en cuenta que el cuadro es editable y debe contener un número que indique el número de irregularidades que deben detectarse antes de que comience la alerta. + +.. figura:: media/image174.png + + Alert settings. + +En la parte inferior de la página asocie el KPI de interés y seleccione la acción haciendo clic en el botón **Agregar acción** botón. Aquí puedes elegir entre **Enviar correo** o **Ejecutar un documento**. + +Si se elige el "Enviar correo", se solicita al usuario que inserte los umbrales que deben ser monitoreados: en caso de que estos últimos sean superados, la funcionalidad envía el correo electrónico a los sujetos indicados. Recuerde insertar todos los campos obligatorios (nombre, umbrales y asuntos del correo) y, en particular, seleccionar el usuario al que se envía el correo electrónico. Tenga en cuenta que en el cuadro asuntos de correo puede escribir tanto direcciones de correo como nombres de usuario (por ejemplo, "user_admin"), ayudado por el texto de inserción automática es como se muestra en la siguiente figura. De hecho, el servidor de Knowage seleccionará la dirección de correo del atributo de perfil asociado a ese usuario. Por lo tanto, recomendamos establecer el atributo de perfil previamente. En particular, recuerde que el atributo profile *mosto* Se denomina implementación de Alert "\ *Correo electrónico*\ ". + +.. \_sendemailconf: +.. figura:: media/image175.png + + Send email configuration. + +Además, tenga en cuenta que el cuerpo del correo puede contener un mensaje de texto sin formato o una tabla que muestre los valores de KPI registrados que activaron la alerta. Para habilitar la opción de visualización de tablas, debe insertar el marcador de posición \*TABLE_VALUE\* en el cuerpo del correo como se muestra en la figura siguiente. + +.. figura:: media/image176.png + +Envíe un correo electrónico que contenga una tabla con los valores detectados. + +Si se selecciona la opción "Ejecutar un documento", la alerta iniciará un proceso ETL cuando se detecten los umbrales elegidos. Es decir, la funcionalidad lanzará un proceso para ejecutar acciones por lotes como la escritura de tablas adecuadas de un DWH, la creación de un archivo, la llamada a un servicio de registro. Tenga en cuenta que el proceso ETL debe existir como un documento en el servidor de Knowage. En la siguiente figura se da un ejemplo. + +Guarde la acción y los valores de configuración de la alerta para almacenar la alerta. Recuerde que es posible programar más de un monitoreo sobre la misma definición de alerta. + +.. \_executedocument: +.. figura:: media/image177.png + + Execute document configuration. diff --git a/functionalities-guide/analytical-document/index.es.rst b/functionalities-guide/analytical-document/index.es.rst new file mode 100644 index 00000000..7cd8ce1a --- /dev/null +++ b/functionalities-guide/analytical-document/index.es.rst @@ -0,0 +1,394 @@ +# Documento analítico + +El *modelo analítico* es el núcleo de Knowage Server y cubre toda la gama de necesidades analíticas, proporcionando muchas soluciones para cada área analítica, como informes, gráficos, documentos OLAP, KPI, etc. + +El elemento principal del modelo analítico es el llamado *documento analítico*, palabra utilizada para agrupar bajo un concepto común todos los diferentes tipos de documentos que se pueden desarrollar con Knowage (informe, gráfico, cabina, etc.) a la hora de realizar un análisis de BI. + +En este capítulo describimos paso a paso cómo crear un nuevo documento analítico. Existen muchos tipos de documentos diferentes, cada uno con sus propias peculiaridades. Aquí proporcionamos una visión general genérica sobre las características comunes, nos centraremos en las peculiaridades de los tipos disponibles en cada parte dedicada. + +## Conceptos principales + +La creación y gestión de documentos analíticos en Knowage involucra diferentes elementos: + +Plantilla +La plantilla define el diseño estándar de un documento, incluyendo información específica sobre su apariencia y la forma en que se debe mostrar el contenido. Las plantillas se pueden codificar a mano o utilizando diseñadores de Knowage Studio, cuando estén disponibles. Para cada documento analítico se mantiene el historial de plantillas. Las plantillas antiguas se pueden restaurar si es necesario. Se guarda una nueva versión en cada implementación, ya sea manual o desde Knowage Studio. +Conjunto de datos +Cada documento está asociado a uno o más conjuntos de datos. El conjunto de datos proporciona datos reales que se representarán de acuerdo con la plantilla definida. Es decir, el dataset proporciona el contenido real del análisis y la plantilla se encarga de darle una estructura significativa. +Origen de datos +Para recuperar datos a través del conjunto de datos, se debe definir una fuente de información. Dependiendo del tipo de documento, el origen de datos puede estar asociado al documento directa o implícitamente (a través del conjunto de datos). +Parámetros +Los parámetros permiten la conexión entre el documento y los controladores analíticos asociados a él. En otras palabras, en el momento de la ejecución del documento, cada controlador genera un valor que se asigna al parámetro correspondiente. + +Estos elementos se combinan dentro de cada motor de documentos, con el fin de producir diferentes documentos analíticos. Este proceso genera una salida HTML, a la que se puede acceder y navegar utilizando un navegador web. Se admiten otros formatos de salida, incluidos XLS, CSV, PDF, XML. + +.. figura:: media/image57.png + +Componentes del documento analítico knowage. + +Tipos de documentos + +``` + +Regardless of their type, all analytical documents interact with some generic components (such as cross-services) and with the specific engine that generate them (e.g. Report engine, OLAP engine). Therefore, all analytical documents are managed in the same way in terms of: + +- document storage and versioning; +- document life cycle, based on a specific approval process including different status (development, test, released, suspended); +- multiple positioning on the repository and indirectly first visibility level; +- rules to restrict document visibility to some end user profiles; +- management of analytical drivers; +- multi-format export logic; +- attribution of business metadata; +- scheduled execution; +- collection of auditing and monitoring data; +- adding end user notes; +- adding bookmarks; +- end user evaluation; +- sending the document by email; +- on-line or off-line (scheduled) execution. + +This means that the above mentioned features are also inherited by every new engine that is developed or integrated into Knowage. + +In the next sections we describe in detail how to create and manage analytical documents in Knowage. + +Register an analytical document +----------------------------------- + +There are two different ways to create a new document on Knowage Server. The first option involves Knowage Studio: within it you can simply click on **Deploy** and the document window will open with pre-filled options. Please note that Knowage Studio can be used to create Birt or Dashboard document only. + +.. note:: + **Deploy a document from Knowage Studio** + + Knowage Studio is the tool that allows to design and upload documents onto Knowage Server. Please refer to the dedicated section for full details and examples. + +The second option is to manually create the document on the Server. This is the most general way since the Studio designer is not yet available for all documents types. + +Analytical documents on Server +``` + +En primer lugar, haga clic en **Desarrollo de documentos** desde el menú Funcionalidades de BI, como se muestra . + +.. figura:: media/image58.png + + Documents Development button. + +De forma predeterminada, la página se divide en dos partes, como se muestra en la figura a continuación: en el lado izquierdo está el árbol de funcionalidad que representa la estructura de carpetas, mientras que a la derecha puede ver la lista de todos los documentos contenidos en la carpeta seleccionada. + +.. figura:: media/image59.png + + Documents Development section. + +Puede cambiar a la vista de vista previa del documento haciendo clic en el icono de cuadrícula en la esquina superior derecha, como se muestra en la figura a continuación. + +.. \_changingdocumentsview: +.. figura:: media/image60.png + + Changing documents view. + +Cada línea muestra la etiqueta, el nombre, el autor y el tipo de documento, mientras que el botón de reproducción al final de cada fila ejecuta el documento. Además, al hacer clic en una línea se abre un panel lateral a la derecha de la página. Aquí puede ver más información de metadatos, como la descripción del documento, el estado y la fecha de creación. + +.. figura:: media/image61.png + + Side panel. + +En la parte superior de este panel lateral se encuentran cuatro botones: + +* |image60| ejecutar el documento; + +.. |image60| imagen:: media/image62.png +:ancho: 30 + +* |image61| acceder a los detalles del documento; + +.. |image61| imagen:: media/image63.png +:ancho: 30 + +* |image62| clonar el elemento; + +.. |image62| imagen:: media/image64.png +:ancho: 30 + +* |image63| borrar el documento. + +.. |image63| imagen:: media/image65.png +:ancho: 30 + +La siguiente figura muestra el panel de detalles de un documento. A la izquierda, se muestran los detalles del documento, incluidos el nombre, el tipo, el conjunto de datos y el estado. A la derecha, puede ver el árbol de funcionalidades y la posición del documento. Si desea copiar o mover un documento de una carpeta a otra, marque o desmarque las carpetas correspondientes. + +.. \_detailpanelofknowanalydoc: +.. figura:: media/image66.png + + Detail panel of Knowage analytical document. + +Para crear un nuevo documento, debe hacer clic en el botón rojo más en la esquina superior derecha del **Desarrollo de documentos** página. Los diferentes tipos de documentos que puedes crear son: **Cabina** y **Documento genérico**. Tenga en cuenta que no todos están disponibles en todos los productos de Knowage. + +Para crear un nuevo documento genérico, haga clic en el botón mencionado anteriormente y seleccione **Documento genérico**. Se le mostrará una ventana como la de la figura anterior, pero con campos vacíos, para permitirle definir los detalles del documento. + +En primer lugar, elija una etiqueta, un nombre y una descripción. Es importante señalar que la etiqueta es el identificador único del documento en Knowage Server. Luego, seleccione el tipo de documento y el motor apropiado en los menús desplegables, de acuerdo con el documento que está desarrollando (consulte la figura a continuación). + +.. figura:: media/image67.png + + Select Type and Engine for a new document. + +Ahora debe seleccionar el conjunto de datos y / o la fuente de datos que alimentará su documento con datos. En este ejemplo, puede ver la ventana emergente con conjuntos de datos para seleccionar en la siguiente figura. + +.. figura:: media/image68.png + + Selecting a dataset for the document. + +Ambos deberían haber sido ya definidos en los apartados correspondientes para que Knowage los muestre en las opciones disponibles de los menús. Puede seleccionar el origen de datos en el menú desplegable. Y seleccione el conjunto de datos en la ventana emergente y haga clic en guardar. + +Tenga en cuenta que algunos tipos de documento no requieren la definición de un conjunto de datos en este momento porque utilizan conjuntos de datos incrustados. Dependiendo del tipo, también puede ser necesario seleccionar el origen de datos. + +Es recomendable guardar regularmente el documento en este proceso, haciendo clic en el botón relacionado guardar en la esquina superior derecha de la ventana. + +Ciclo de vida del documento +^^^^^^^^^^^^^^^^^^ + +El siguiente paso es elegir el estado del documento utilizando el **Estado** menú desplegable. De hecho, en cualquier momento, cada documento está asociado a un estado, que generalmente cambiará con el tiempo después del desarrollo del proyecto. Esos estados son: + +* desarrollo; +* prueba; +* liberado; +* suspendido. + +Tras la creación, el documento está de forma predeterminada en estado de desarrollo. Cada vez que cargue una nueva plantilla o realice cambios en el documento, se recomienda que el estado se actualice para reflejar su estado de desarrollo real. + +La razón principal de esto es que el estado del documento tiene un impacto en su accesibilidad. Como se discutió en el modelo de comportamiento, Knowage define los tipos de roles (administrador, desarrollador, probador, usuario). Los estados son compatibles con el tipo de rol correspondiente. Los administradores pueden cambiar el estado de los documentos en cualquier momento. Los desarrolladores no pueden acceder solo a los documentos con estado de prueba. Los evaluadores no pueden ver los documentos en desarrollo o en estado suspendido. Los usuarios solo pueden ejecutar documentos en estado liberado. Tenga en cuenta que un probador puede cambiar el estado de un documento de la prueba al desarrollo. + +.. importante:: +**Solo Enterprise Edition** + + In KnowageER you may also decide to temporary "lock" a document while he is working with it: it is enough to set the **Lock by user** item. This prevent other developers from modifying the same document you are working on. + +Control de versiones de plantillas +^^^^^^^^^^^^^^^^^^^ + +Cuando registra un documento en el servidor, debe asociarle una plantilla. Haga clic en la pestaña **Historia** y luego en el botón **Hojear** para elegir una plantilla de su sistema de archivos local y cargarla. + +.. \_templateversionforanalydoc: +.. figura:: media/image69.png + +Es posible que haya editado la plantilla a mano o utilizando el diseñador de Studio. Claramente, no tendrá que cargar la plantilla si está utilizando la implementación automática desde Studio. + +Knowage Server admite el control de versiones de las plantillas cargadas, como se muestra a continuación. Para verlos, haga clic en la pestaña **Historia**. Todas las plantillas se guardan con su fecha y nombre, y se pueden cargar o eliminar fácilmente. Para subir una plantilla, haga clic en el botón **Hojear** para elegir una plantilla de su sistema de archivos local y cargarla: se cargará la nueva plantilla. Usando la misma lista puedes descargar o eliminar una plantilla. + +.. figura:: media/image70.png + + Template versioning for analytical documents. + +Visibilidad de documentos +^^^^^^^^^^^^^^^^^^^ + +Después de haber definido todos los detalles, debe elegir dónde se guardará el documento analítico en el árbol de funcionalidades. Esta elección tiene un impacto en la visibilidad del documento. Dado que las carpetas en el árbol de funcionalidad están sujetas a diferentes políticas de acceso, que se pueden establecer al crear el nodo, cada documento guardado en esa carpeta heredará los permisos en consecuencia. + +.. advertencia:: +**Estructura y derechos del repositorio** + + The **Functionalities tree** is Knowage document repository. It is managed by administrator, who is in charge to profile user visibility too. + +Tenga en cuenta que el mismo documento se puede guardar en diferentes puntos del árbol de funcionalidades. Esto permite al administrador hacer que el documento sea accesible para varios roles en función de las reglas de visibilidad definidas para las carpetas que lo contienen. A la derecha, puede elegir dónde desea guardar el documento marcando la carpeta correspondiente en el árbol. Si desea guardarlo en varias ubicaciones, márquelas todas antes de guardar. Cada usuario que tenga acceso a la carpeta que contiene verá el documento. + +.. \_functionaltreedocsav: +.. figura:: media/image66.png + + Functionality Tree, document saving settings. + +## Reglas de visibilidad + +Además del mecanismo estándar admitido por el árbol de funcionalidades, es posible personalizar aún más el acceso a un documento en función de los atributos del perfil de usuario. Esto permite a los administradores controlar el acceso a los documentos a un nivel muy detallado, más allá de las simples políticas basadas en repositorios. + +Esto se puede hacer editando las condiciones en el **Restricciones de visibilidad** sección en el lado derecho de **Información** tablero. Para agregar una nueva condición, elija un atributo de perfil del menú desplegable y asígnele un valor. Esto agregará una nueva condición que debe verificarse para permitir que un usuario acceda al documento. De la misma manera, puede agregar más condiciones y, posiblemente, eliminarlas todas haciendo clic en el borrador. + +.. figura:: media/image73.png + + Visibility restrictions. + +## Asociación con conductores analíticos + +Ya hemos discutido el papel de los impulsores analíticos y cómo se conectan a los documentos analíticos a través de parámetros. En esta sección mostraremos cómo definir prácticamente esta asociación. + +Suponemos que la plantilla de documento y los conjuntos de datos están configurados correctamente en términos de definición de parámetros. En particular, deberían haber sido referenciados correctamente con su URL. + +Para agregar un nuevo parámetro, puede hacer clic en la pestaña **Controladores** y luego en un **Agregar** , vea la siguiente figura. + +.. figura:: media/image74.png + + Association with analytical driver panel. + +Elija un nombre para el título del conductor. A continuación, elija el controlador analítico en el menú desplegable que desea asociar al documento. + +Una vez que haya seleccionado el controlador, debe escribir el **URL exacta** del parámetro correspondiente. A continuación, establezca las diferentes características asociadas al controlador: puede configurar su visibilidad y decidir si es necesario y multivalor. De forma predeterminada, el parámetro es visible, no obligatorio y no multivalor. + +Si desea que el documento no sea visible para los usuarios finales, desmarque el botón **Visible** casilla de verificación. Tenga en cuenta que el parámetro seguirá existiendo y recibirá valores del controlador asociado. Sin embargo, esto se ocultará y el usuario final no podrá elegir ningún valor para este parámetro. + +Si desea configurarlo como un parámetro requerido, simplemente haga clic en **verdadero**. En este caso, no se establece ningún valor predeterminado. Se le pedirá al usuario final que elija el valor del parámetro antes de abrir el documento. + +Del mismo modo, para establecer un parámetro como multivalor, haga clic en **verdadero**, de esta manera el usuario puede realizar múltiples selecciones entre sus valores. + +Una vez que haya completado la definición de un parámetro, puede guardarlo haciendo clic en principal **Salvar** en la esquina superior derecha. Para agregar más parámetros, haga clic en el botón **Agregar** botón. Repita el mismo procedimiento tantas veces como desee. En este punto, es posible que desee cambiar el orden de los parámetros (es decir, cómo se presentan al usuario). Para hacerlo, haga clic en la flecha en la lista de controladores. + +.. figura:: media/image75.png + + Association with analytical driver panel. + +A continuación veremos algunas operaciones especiales que se pueden realizar sobre los drivers asociados a un documento. + +Correlación entre parámetros + +``` + +In the context of a document, two different parameters may be connected to each other: this means that the possible values of a parameter are limited by the value(s) of another parameter. + +This feature can be useful when two (or more) parameters are logically related. For example, suppose to have a parameter for all the possible countries and another one for all the possible cities. If the user selects a region, it is meaningless to show him all cities: he should only be enabled to choose among the cities in the selected region. + +In general, to configure a correlation within a document you should make sure that the LOV associated with the parent parameter and the one associated to the child parameter share at least one column. This column defines which value from the parent parameter will be applied to the child, in order to constrain the results. + +.. figure:: media/image79.png + + Definition of the correlation. + +To set the correlation, select child parameter which will show you the details of that particular driver and then click on the **Add condition** button to open pop-up window for defining data correlation. + +.. figure:: media/image80.png + + Adding data correlation. + +Here you need to define: + +- the parent parameter; + +- the type of logical operator, in order to compare values of the parent parameter with values of the child parameter; + +- the column, generated by the child parameter, whose value will be compared with the value of the same column in the parent parameter. + +If a parameter depends on multiple parent parameters, you can define multiple correlations. + +.. figure:: media/image81.png + + Multiple correlations. + +Once defined the correlation, the child parameters will display the labels during the runtime in italics. + +Correlation through LOV and drivers +``` + +En secciones anteriores vimos cómo establecer la correlación a través de la GUI disponible en el panel de detalles del documento, pero también existe la posibilidad de obtener el mismo resultado utilizando el enlace entre LOV y los controladores analíticos. Más en profundidad, el usuario debe haber configurado previamente un controlador que ejecute valores que se puedan usar en la cláusula "where" de una consulta SQL. A continuación, el usuario debe establecer un LOV de tipo de consulta mediante la sintaxis + +Destacamos que el `AD_name` es el nombre del controlador al que el administrador intenta llegar. La sintaxis para establecer la correlación a través de la configuración de LOV es: + +.. code-block:: bash +:caption: Sintaxis para establecer la correlación a través de la configuración de LOV +:linenos: + +$P{AD_name} + +.. figura:: media/image82.png + + Correlation passing driver values to LOV query . + +Como resultado, en la ejecución del documento, tan pronto como el usuario recoja un valor del parámetro "libre", el otro se filtra y mostrará solo el valor relacionado con la selección anterior, como se muestra en la Figura a continuación. + +.. figura:: media/image83.png + + Filtering with correlation. + +Visibilidad controlada + +``` + +Another type of relation between parameters is supported by Knowage. It is possible to define values of a parent parameter that force hiding or showing of a child parameter in the parameters mask. Note that in the first case, the child parameter is hidden by default, while in the second case the parameter is shown by default. + +To set a visibility expression, click on the **Add condition** button on the **Driver visibility conditions** card. + +.. figure:: media/image72.png + + Adding visual correlation + +In the graphical editor you can define visibility rules similarly to correlation ones, as shown in figure below. + +.. figure:: media/image84.png + + Visibility expressions. + +Cross Navigation +--------------------- + +A powerful feature of Knowage analytical documents is cross-navigation, i.e., the ability to navigate documents in a browser-like fashion following logical data flows. Although crossnavigation is uniformly provided on all documents executed in Knowage Server, each type of document has its own modality to set the link pointing to another document. + +Notice that the pointer can reference any Knowage document, regardless of the source document. For example, a BIRT report can point to a chart, a console, a geo or any other analytical document. + +In Knowage there are two main typologies of cross navigation: *internal* and *external*. + +*Internal cross navigation* updates one or more areas of a document by clicking on a series, a text, an image or in general on a selected element of the document. + +*External cross navigation* opens another document by clicking on an element of the main document, allowing in this way the definition of a *navigation path* throughout analytical documents (usually, from very general and aggregated information down to the more detailed and specific information)). Indeed, you can add cross navigation also to a document reached by cross navigation. This can be helpful to go deeper into an analysis, since each cross navigation step could be a deeper visualization of the data displayed in the starting document. + +It is obviously possible to associate more than one cross navigation to a single document. It means that by clicking on different elements of the same document the user can be directed to different documents. + +In this chapter we will examine in depth how to set output/input parameters on documents and, consequently, how to activate the cross navigation. + +The first step is to define the parameters of the target document. These do not necessarily coincide with all the filters applied to the +document. Please refer to Chapter of Behavioural model for more detail on how to manage parameters and their association to documents. + +Therefore it is required to state which parameters among the ones associated to the target document are going to be involved in the navigation. Parameters coming out from the source document are said **output parameters** while the ones that receive values through the association (with the source document) are said **input parameters**. By the way, when declaring the parameters they will be called equally **output parameters** at first, since there is no criterion to distinguish output from input before the navigation is configured. + +The definition of the output parameters is performed using the **Manage outputparameters** button but it differs from document to document, according to its type. We will describe these differences in detail in each dedicated chapter, here we explain the common steps. + +Declaration of the output parameters +``` + +Introduzca el **Detalles del documento** del documento de interés. Luego haga clic en **Parámetros de salida** y luego en el botón **Agregar** para agregar un nuevo parámetro de salida. + +Aquí debe indicar qué parámetros se utilizarán como parámetros de salida. Si, por ejemplo, selecciona el tipo de fecha (consulte la siguiente figura), es posible elegir el formato en el que se ha codificado su fecha. El valor predeterminado está relacionado con la ubicación definida en (**Menú** > **Idiomas**). + +.. \_settinganotuparam: +.. figura:: media/image85.png + + Setting an output parameter. + +Definición de navegación cruzada + +``` + +Finally you need to select the **Cross Navigation Definition** item from the menu to configure the cross navigation. The figure below shows the cross navigation definition window. + +.. figure:: media/image86.png + + Cross navigation GUI. + +It is required to give a name to the navigation; then select the document from which to start the navigation and the target document. The selecting of a document will cause the loading of input/output parameters related to the starting document in the left column and of the possible input parameters of the target document in the right column. + +It is possible to configure the associations between input/output parameters by simply dragging and dropping a parameter from the left column on another of the right column. + +.. figure:: media/image87.png + + Setting the cross navigation through the tree item. + +.. figure:: media/image88.png + + Relating parameters. + +Once set, the association is highlighted as in Figure below. + +.. figure:: media/image89.png + + Association between parameters. + +To assign fixed values to target parameters it is necessary to edit first the box labelled **Fixed value parameter** and click on the **plus** icon. Then the value can be associated as fixed value of the one or more target parameters. Remember to click on the **Ok** button to save the cross navigation just set. + +As you know, it is possible to define multiple cross navigation starting by the same document. In this case the system will show a popup window to choose the one that you want execute. +It is possible set a specific description for each cross navigation so that will be easy to recognize the right navigation definition to use. In the same way it is possible set the text of the bread crumb and personalize it. +For both attributes it is possible show parameters (of input or output type) values through the syntax $P{parameter_name}. Just parameters of source documents are available. + +.. figure:: media/image90.png + + Example of parametric description and breadcrumb text + +.. figure:: media/image91.png + + Example of popup selection for more cross navigation definition (with params) + +.. figure:: media/image92.png + + Example of breadcrumb with params +``` diff --git a/functionalities-guide/basic-data-access/index.es.rst b/functionalities-guide/basic-data-access/index.es.rst new file mode 100644 index 00000000..8a9da486 --- /dev/null +++ b/functionalities-guide/basic-data-access/index.es.rst @@ -0,0 +1,139 @@ +# Acceso básico a datos + +Este capítulo describe las funciones avanzadas, es decir, disponibles solo en los productos KnowageBD y KnowageSI, para acceder a los datos como usuario final. + +.. importante:: +**Edición Enterprise** + + If you purchased Knowage EE, the following features are available only in KnowageBD and KnowageSI products + +Un conjunto de datos es una forma de leer datos de diferentes fuentes y representa la parte de los datos utilizada por varios documentos. Supongamos que desea crear un gráfico de barras que muestre la tendencia de ventas para el año en curso; en este caso, debe pasar al documento el monto total de ventas para cada mes del año en curso. Puede crear su propio conjunto de datos cargando un archivo XLS o CSV o utilizar un conjunto de datos ya definido. Knowage también le ofrece la posibilidad de descargar datos abiertos de WEB gracias a la integración CKAN. Además, puede crear su propio conjunto de datos y más completo a partir de diferentes fuentes a través de la federación de conjuntos de datos. A continuación describiremos todas estas funcionalidades. + +Supongamos que debemos introducir, con las credenciales de usuario final, el área de gestión de datos haciendo clic en el botón **Área de trabajo** del menú Funcionalidades de BI como se muestra en la figura siguiente y el icono de funcionalidades de BI **Datos** de la ventana. + +.. figura:: media/image56.PNG + + Access to **My Data** area + +Después tienes las subsecciones: **Conjunto de datos** y **Modelos**. Escoger **Modelos** para explorar los modelos y el **Federación de conjuntos de datos** área. Tenga en cuenta que el **Federación de conjuntos de datos** la funcionalidad solo está disponible en KnowageBD y KnowageSI. + +## Conjunto de datos + +En el área "Dataset" encontramos todos los datasets clasificados según sus tipos. Los conjuntos de datos se clasifican de la siguiente manera: + +* **Mi conjunto de datos**: conjuntos de datos creados por usted mismo cargando un archivo CSV o XLS o creando una consulta sobre un modelo de negocio utilizando la interfaz Qbe; +* **Conjunto de datos empresarial**: conjuntos de datos certificados, es decir, conjuntos de datos creados por los usuarios técnicos/expertos y compartidos con el usuario final. +* **Conjunto de datos compartido**: conjuntos de datos creados y compartidos por otros usuarios finales; +* **Conjunto de datos CKAN**: en esta área puede descargar conjuntos de datos públicos y visualizar sus conjuntos de datos CKAN; +* **Todo el conjunto de datos**: en esta carpeta se almacenan todos los conjuntos de datos disponibles, es decir, todos los conjuntos de datos contenidos en las clases que acabamos de describir. + +Mi conjunto de datos + +``` + +In this area you can create datasets uploading your own files. + +Click **Create Dataset** to open the dataset wizard which guides you through the dataset creation. You can choose between XLS or CSV file as in the following figure. + +.. _datasetcreation: +.. figure:: media/image7.png + + Dataset creation. + +In the example shown in the next figure, we upload an XLS file. + +.. _uploadingxlsdat: +.. figure:: media/image8.png + + Uploading XLS for dataset. + +The wizard, shown below, leads the user to insert some information to configure the dataset. For instance to specify the number of rows to skip or to limit and which sheet (of the XLS file) to pick up values from. + +.. _configfeatures: +.. figure:: media/image9.png + + Configuration features. + +Once you have uploaded the file, you can check and define the metadata (measure or attribute) of each column. To switch a measure to an **attribute** (or viceversa), click on **Value** column of the interested row field as shown below. + +.. figure:: media/image101112.png + + Change metadata. + +Just few steps before saving the dataset: + +- Check the data preview in order to verify the accuracy of your data; +- enable or disable the persistence of dataset. Thanks to this functionality the server creates a snapshot of the extracted data in order to avoid to reload the dataset each time that the user revokes it; +- finally, name and save the dataset as shown below. + +.. figure:: media/image1314.png + + Saving dataset. + +As we discussed previously, you find all created datasets under **My dataset** area. You can share/unshare them by clicking on the **share** icon (have a look at the next figure). The colour of the icon changes from white to red when sharing is turned to active. A shared dataset is visible to all other users having your same role. + +Note that dedicated area “\ **Shared Dataset**\ ” contains all acquired datasets thanks to the sharing of other users. + +.. _sharedataset: +.. figure:: media/image15.png + + Share a dataset. + +CKAN integration +``` + +Gracias a la integración de CKAN, puede acceder fácilmente a los conjuntos de datos publicados en la World Wide Web (por ejemplo, datahub.io, data.gov, data.lab.fiware.org, dati.gov.it y más). De hecho, CKAN es la plataforma de portal de datos de código abierto líder en el mundo. Es un potente sistema de gestión de datos que hace que los datos sean accesibles al proporcionar herramientas para agilizar la publicación, el intercambio, la búsqueda y el uso de datos. CKAN está dirigido a editores de datos (gobiernos nacionales y regionales, empresas y organizaciones) que desean que sus datos sean abiertos y estén disponibles. Por lo tanto, puede buscar y manejar datos abiertos de manera de autoservicio. + +.. advertencia:: +**Conjuntos de datos CKAN** + + CKAN datasets can be divided into four main categories: “Public”, “Organization private”, “Acquired”, “User private”. You can download and use only the datasets having a **Public** category. + +Método de acceso a conjuntos de datos CKAN +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Para comenzar a usar conjuntos de datos CKAN dentro de Knowage suite, vaya al **Conjunto de datos CKAN** en la subsección "Conjunto de datos" de la sección "Datos" en "Mi espacio de trabajo". Como se muestra en la figura a continuación, elija del cuadro combinado el repositorio que le interesa y luego haga clic en el nombre del repositorio para acceder a él. + +.. figura:: media/image16.png + + CKAN Repositories. + +Se mostrará una vista previa de los conjuntos de datos almacenados en el repositorio elegido. + +Estos aún no son utilizables, pero puede comenzar a manejarlos como mostraremos en las siguientes secciones. Los conjuntos de datos se muestran con su nombre y descripción. Al mover el cursor sobre un conjunto de datos, aparecerá una lista de acciones disponibles. Haciendo clic en el botón **Información** , un conjunto de información del recurso CKAN original y sobre el estado del conjunto de datos (por ejemplo, visibilidad, fecha de última modificación) no puede ser mostrado por Knowage, como en la siguiente figura. Para utilizar uno de ellos hay que importar información de metadatos y luego analizar el conjunto de datos bajo demanda. + +.. figura:: media/image17.png + + CKAN dataset details. + +Exportar conjunto de datos +^^^^^^^^^^^^^^ + +Tenga en cuenta que una vez que se ha creado el conjunto de datos, el usuario puede resultar útil para obtener un Excel de él. Knowage ha diseñado un botón específico para satisfacer esta necesidad que el usuario puede encontrar explorando el panel de detalles del conjunto de datos, como se informa a continuación. + +.. figura:: media/image18.png + + Export dataset. + +Guardar y manejar el conjunto de datos +^^^^^^^^^^^^^^^^^^^^^^^ + +Si desea utilizar un conjunto de datos que aún no se ha utilizado, cualquier acción en él iniciará el asistente de importación de metadatos. Se accede a él haciendo clic en el icono de la lupa. Como primer paso, debe insertar algunos parámetros obligatorios para establecer la configuración del analizador. + +Como segundo paso, el usuario debe especificar cómo aparecerá el conjunto de datos y verificar los metadatos. Tenga cuidado de elegir el tipo de datos adecuado (Cadena, Entero, Doble) y el tipo de campo (Medida, Atributo). Después de eso, haga clic en **Próximo** para ver los resultados de la validación, confirme y finalice la importación del conjunto de datos. Una vez completada la importación del conjunto de datos, el conjunto de datos seleccionado aparecerá en el **Conjunto de datos** pestaña también. Estas acciones acaban de aparecer en el cambio de conjunto de datos para los conjuntos de datos descargados. En particular, tiene el icono en forma de ojo para actualizar el conjunto de datos o cambiar los metadatos repitiendo el proceso de descarga y el icono de la lupa para consultarlo a través de la interfaz QbE. + +## Modelos + +Aquí encontrará los modelos que un usuario técnico ha construido para usted. Puede consultarlo utilizando la interfaz QbE y crear su propio conjunto de datos a partir de ellos. + +## Federación de conjuntos de datos + +La federación de conjuntos de datos es una funcionalidad disponible solo en KnowageBD y KnowageSI. Gracias a la funcionalidad de federación de datos, puede crear un nuevo conjunto de datos que combine dos o más conjuntos de datos de acuerdo con sus permisos de rol. Permítanos darle un ejemplo. Supongamos que ha almacenado en una base de datos la información de sus productos (es decir, ventas, costos, promociones ecc.) y encuentra como datos abiertos los comentarios de los clientes sobre estos productos. Si crea conjuntos de datos en estos recursos de federación de conjuntos de datos que comparten al menos una columna, puede unirlos en la columna común y mejorar el análisis. + +Haga clic en **Crear federación** para ver todos los conjuntos de datos disponibles y elegir los que desea federar. Clic **Próximo** y elija en qué columnas debe realizarse la unión y haga clic en el icono más para agregarlo al cuadro de diálogo **Lista de asociaciones**. En nuestro ejemplo de la siguiente figura elegimos Producto. + +.. figura:: media/image19.png + + Federated dataset details. + +Una vez guardada, la nueva federación se ha creado en **Definición de federación** y puede encontrarlo en la definición de federación. Ábralo haciendo clic en el icono de la lupa en la federación. De esta manera lo abres con la herramienta QbE. Todos los detalles sobre cómo utilizar la interfaz QbE para realizar consultas gratuitas se pueden encontrar en el capítulo dedicado. Puede crear nuevos conjuntos de datos, guardarlos y recuperarlos desde el **Conjunto de datos** sección. diff --git a/functionalities-guide/behavioural-model/index.es.rst b/functionalities-guide/behavioural-model/index.es.rst new file mode 100644 index 00000000..afd9ee70 --- /dev/null +++ b/functionalities-guide/behavioural-model/index.es.rst @@ -0,0 +1,359 @@ +# Modelo de comportamiento + +Un tema importante a enfrentar antes de iniciar un nuevo proyecto es cómo crear y gestionar los llamados *modelo conductual*. + +El *modelo conductual* regula la visibilidad de documentos y datos según los roles y perfiles de los usuarios finales. + +Responde principalmente a las siguientes preguntas: + +* La OMS utiliza la solución de inteligencia empresarial (perfil de usuario); +* LO que es visible para los usuarios, en términos de documentos y datos (derechos de repositorio y controladores analíticos); +* CÓMO trabajan los usuarios con sus documentos (controladores analíticos y configuración del entorno de presentación). + +La creación y la gestión del modelo de comportamiento corre a cargo de Knowage Administrator. Sin embargo, cuando se ha diseñado y construido, también debe compartirse con los desarrolladores. De hecho, en la fase de desarrollo hay que ser consciente de la jerarquía de visibilidad. Necesita esta información para establecer correctamente las opciones del documento. + +## Roles, usuarios y atributos + +Los usuarios de Knowage se definen por: + +* Identidades +* Papeles +* Perfiles. + +El *identidad* de un usuario consiste en todos los datos utilizados para identificar a ese usuario, es decir, un nombre de usuario y una contraseña, así como un nombre completo legible por humanos. + +El *perfil* de un usuario consiste en un conjunto de propiedades llamadas atributos, que describen información general sobre el usuario, por ejemplo, edad y sexo, pero también propiedades específicas del dominio, como la unidad organizativa a la que pertenece. Algunos atributos, como el nombre y el correo electrónico, se definen de forma predeterminada en Knowage. Otros pueden ser agregados por el administrador del modelo, como se explica en las siguientes secciones. + +El *rol* de un usuario representa una categorización de un grupo de usuarios. Estos roles pueden corresponder a puestos específicos en la empresa, por ejemplo, "gerente general" o un "director de ventas", o a un puesto con respecto al proyecto de BI, por ejemplo, "administrador de datos" y "desarrollador de BI". Diferentes usuarios pueden tener el mismo rol, así como el mismo usuario puede tener múltiples roles. + +No tendrá subvenciones para crear nuevos roles o usuarios, pero se le pedirá que los haga coincidir durante las fases de profanación de documentos. A continuación vamos a describir los elementos necesarios para añadir parámetros. Estos elementos también implican la profilación. Para concluir veremos cómo gestionar la accesibilidad a la hora de crear un documento. + +## Controladores analíticos + +Un controlador analítico (en adelante, simplemente conductor) modela un concepto o un dato utilizado con frecuencia como criterio distintivo en el contexto global de datos. Un conductor destaca los conceptos que guían el análisis, proporcionando una representación única de ellos y describiendo cómo se muestran y comprueban de acuerdo con los roles de los usuarios finales. Cuando se conecta a documentos analíticos, un controlador produce un parámetro explícito o implícito utilizado para filtrar datos. + +.. \_parametrreportbehav: +.. figura:: media/image39.png + + Parametric Report. + +La figura anterior representa un informe con dos parámetros: + +* el Departamento, un campo obligatorio, que se muestra como un cuadro combinado y con posibles valores: Bebidas alcohólicas, Productos horneados, Productos de panadería, etc.; +* el Rango de edad, un campo obligatorio, que se muestra como lista de valores y con posibles valores 0-10, 10-20 y así sucesivamente. + +Todos estos aspectos están regulados por el controlador analítico detrás de cada parámetro. En particular, cada conductor proporciona muchos *modos de uso*definitorio: + +* Quién está involucrado en un modo de uso específico, en términos de una lista de roles de usuario final, teniendo en cuenta que un rol puede asociarse a un solo modo de uso. +* A qué datos puede acceder y cómo se presentan al usuario final para su posible selección. Esta información es proporcionada por el llamado *Lista de valores (LOV)*. +* Cómo comprobar la validez de los valores elegidos. Esta información es proporcionada por el llamado *Comprobar*. + +En otros términos, cada modo de uso se refiere a un método de visualización inicial y contenido (LOV), a una o más reglas de validación (check) y a uno o más roles de usuario final (roles). La lógica de un controlador se representa en la figura siguiente. + +.. figura:: media/image40.png + + Analytical driver schema. + +Consideremos el siguiente ejemplo. Necesitamos representar el concepto de "familia de productos". Dado que este es un impulsor común y discriminatorio para el análisis empresarial, se codificará un controlador analítico, con todas sus reglas de comportamiento, tales como: + +* si el usuario es un operador de centro de llamadas o un usuario que proporciona soporte interno, puede escribir manualmente la familia de productos que desea seleccionar. Este valor se verificará formalmente (debe ser un texto) y se verificará en el registro de la familia de productos. +* si el usuario es un director de marca de producto o un secretario operativo, puede elegir el valor de una lista precargada de todas las familias de productos pertenecientes a su marca. Por esta razón, el valor no necesita ninguna comprobación. + +.. figura:: media/image41.png + + Analytical driver schema - Example. + +Una vez definido, un conductor puede relacionarse con muchos documentos, impulsando su comportamiento y filtros de una manera común. De esta manera, un usuario que ejecuta diferentes documentos que utilizan los mismos controladores siempre recibe el mismo formulario de parámetros, aplicando los mismos filtros sobre los datos mostrados. De hecho, cuando un usuario autenticado (con sus roles y perfil) ejecuta un documento analítico, se leen sus metadatos técnicos, principalmente en términos de plantilla de documento y controladores relacionados. En base a ellos, se produce una página personalizada para la entrada de parámetros, de acuerdo con la lógica del controlador para el rol de usuario final. Los valores seleccionados se validan y el resultado final llega al usuario. La siguiente figura muestra este proceso. + +Gracias a los controladores analíticos, un solo documento es capaz de cubrir las demandas analíticas de varias categorías de usuarios, con ventajas notables en términos de: + +* reducción del número de documentos que deben elaborarse y mantenerse, +* coherencia en la solicitud de parámetros, +* reducción de la complejidad en el desarrollo de documentos, gracias a la separación entre cuestiones de seguridad y desarrollo masivo, +* simple mantenimiento de la seguridad (visibilidad sobre los datos) a lo largo del tiempo, a pesar del aumento de documentos desarrollados o motores añadidos. + +En los siguientes párrafos explicamos cómo crear un nuevo controlador analítico junto con sus componentes básicos. + +.. \_overallprocess: +.. figura:: media/image42.png + + Overall process. + +Creación de una lista de valor + +``` + +A *List Of Value* (LOV), is a collection of data organized in attribute-value fashion. For example, the LOV in LOV example retrieves id, name and food family for a product. + +.. code-block:: bash + :caption: LOV example + :linenos: + + {195, High Top Almonds, Food}; + {522, Tell Tale Walnuts, Food}; + {844, Very Good Soda, Drink}; + +There may be multiple attributes in a LOV, but only one of them is the core value that is actually used in the analytical driver. Other values have a descriptive function: they can be used to provide a human readable description of the LOV, as well as to store information used, for example, to correlate analytical drivers. In our example, the core value is the customer’s id, while the others are additional data describing the customer. Knowage allows to create different types of LOV: + +- **Query**: SQL query to retrieve values from the database; +- **Script**: Groovy or JavaScript to dynamically return values; +- **List of fixed values**: Values are defined statically at LOV creation time; +- **Java objects**: External object invoked by name that returns the list of values; +- **Dataset**: Dataset already defined in Knowage Server that is used to retrieve values. Note that the dataset must not contain parameters, while profile attributes are allowed. + +.. _lovlistbehav: +.. figure:: media/image43.png + + LOV list. + +To create and manage LOVs, select **Behavioural Model** > **Lovs Management** from the developer menu. The entire list of available LOVs appears, as shown in figure above. For each LOV, the list shows the label, description and type; to see the details of a LOV the user must simply select it and they will appear in the right half of the page. On the contrary, to delete one dataset click on the icon |image37| available at the end of the row. Notice that you cannot delete a LOV if a driver is currently using it. + +.. |image37| image:: media/image44.png + :width: 30 + +To create a new LOV, click on the icon |image38| at the top right corner of the page. The LOV creation interface will open, where you can set label, name and description, choose the LOV type and define its values accordingly. + +.. |image38| image:: media/image45.png + :width: 30 + +.. figure:: media/image46.png + + LOV Creation interface. + +Once completed the form, click on **Preview** button to enable the **Test** button. Notice that you cannot save the LOV without testing it, since this allows to detect errors before the LOV is actually used in a driver and associated to a document. After testing, you will be able to define which column is the actual value of the LOV, i.e., which value will be passed to the analytical driver using this LOV. Only *one* column can be the value attribute and only *one* column can be chosen as Descriptive attribute, while the others can be visible. The two figures below exhibit an example. Columns that are not visible can be used for correlating drivers. + +.. _previewandteslov1: +.. figure:: media/image47.png + + Preview and Test of the LOV. + +.. _previewandteslov2: +.. figure:: media/image48.png + + Preview and Test of the LOV. + +.. note:: + **Correlating analytical drivers** + + Drivers can be correlated so that the value of the first driver is used as a parameter to select values in the second. Read more at *Analytical document* chapter. + +We stress that the visibility of specific fields serve to improved human readability when applying filters to documents handled by third users. Moreover it is possible to choose (refer to next figure) between **simple**, **tree** and **tree with selectable internal nodes** typology of LOV. The last two are hierarchical and let the user visualize the parameters together with their logical tree structure. + +.. _hierarchicallvdef: +.. figure:: media/image49.png + + Hierarchical LOV definition. + +.. note:: + **Create a LOV for the default value of an analytical driver of type Manual Input Date** + + This note is useful when using an analytical driver of type Date with an input of type Manual. In the case you want to use a particular date as default value for that driver, you have to use this syntax for the LOV: select '2017-09-10#yyyy-MM-dd' as fixed_date. Instead of the fixed date 2017-09-10 you can also use as default date the today date for example; in this case you can use a query of this type: select concat(to_date(now()) ,'#yyyy-MM-dd') as today. The most important thing is to concat to the default date you want to use the string #yyyy-MM-dd. + +.. note:: + **Create a LOV for the default value of an analytical driver with a hierarchical LOV** + + In case you want to add a default value to an analytical driver with an input of type hierarchical LOV you need to use another hierarchical LOV with the default values desired. If the analytical driver LOV is of type *Tree* then the default LOV need to be of type *Tree* too. The LOV need to have values for the leaf level only. Otherwise, if the analytical driver LOV is of type *Tree selectable inner nodes* the default LOV need to be of the same type. The default LOV may have values for one of the level used in the hierarchical LOV. For example, suppose you have an analytical driver with a hierarchical LOV having levels Product Family > Product Category > Product Department. If the hierarchical LOV is of type *Tree* then in the deafult LOV you need to insert one or more values for the level Product Department. Your default LOV have one level, the Product Department. In case the LOV is of type *Tree selectable inner nodes* you can choose one of the three levels. Your default LOV have one level between Product Family, Product Category or Product Department. + +Parametrizing LOVs +~~~~~~~~~~~~~~~~~~ + +Suppose that you need to retrieve a list of values representing all brand names of your products. Then you can use a Query LOV like in Query LOV example: + +.. code-block:: sql + :caption: Query LOV example + :linenos: + + SELECT DISTINCT PRODUCT_FAMILY, BRAND_NAME + FROM PRODUCT + +This is suitable for end users like the general manager who need to see all brands for every product family. Suppose now that another end user is, for example, the food manager. He should not see every brand name, but only those related to the Food product family. This could be done using user’s profile attributes. + +In particular, all query except the ``List of fixed values`` type can be parameterized using profile attributes. This means that, at LOV execution time, the value of the attribute in the user’s profile is assigned to a placeholder in the LOV query/script. Suppose that, in our example, the food manager user has the profile attribute ``pr_family`` equal to ``Food``. You can write this second Query LOV using the placeholder with the standard syntax ``${profile_attribute_name}``, as shown in Parametric query. + +.. code-block:: sql + :caption: Parametric query + :linenos: + + SELECT DISTINCT PRODUCT_FAMILY, BRAND_NAME + FROM PRODUCT + WHERE C.PRODUCT_FAMILY = '${pr_family}' + +Then, at LOV execution time, for the user food manager the query becomes as shown in Runtime placeholder substitute and hence the corresponding LOV will return only the brand names related to the Food product family. + +.. code-block:: sql + :caption: Runtime placeholder substitute + :linenos: + + SELECT DISTINCT PRODUCT_FAMILY, BRAND_NAME + FROM PRODUCT + WHERE C.PRODUCT_FAMILY = 'Food' + +This means that if you are the food manager and your user has the profile attribute ``pr_family=Food``, then you will see only the brand related to the food family as a result of this LOV; while if you are the drink manager and your user has consequently the profile attribute pr_family=Drink, you will see only the brand related to drink family products. + +.. note:: + **Standard profile attributes** + + There are some standard profile attributes always available that don't' need to be defined for each user. These profile attributes are: + + - *user_id* contains the user id of the logged in user + - *user_roles* contains the current user's roles, joined as a SQL IN clause fashion, for example: 'general_management','human_resources_management' + - *TENANT_ID* contains the tenant to which the user belongs + +Note that an information button and a profile attribute button are available to guide user in writing the code properly, using the syntax correctly and typing the right profile attribute name. + +.. figure:: media/image50.png + + Assistance in retrieving syntax and profile attributes. + +Creating a validation rule +``` + +Knowage admite la validación de los parámetros de entrada del documento a través de reglas de validación. Las reglas de validación se pueden definir en **Modelo de comportamiento** > **Gestión de restricciones**. Una regla de validación comprueba los valores de los parámetros proporcionados por las LOV para comprobar que cumplen con las restricciones definidas. + +.. figura:: media/image51.png + + Contraints Management. + +Las comprobaciones predeterminadas de Knowage son: + +* **Alfanumérico**: comprueba si el parámetro es alfanumérico; +* **Numérico**: comprueba si el parámetro es numérico; +* **Cadena de letras**: comprueba si el parámetro es una cadena de letras; +* **Correo electrónico**: comprueba si el parámetro es un correo electrónico; +* **Código Fiscal**: comprueba si el parámetro tiene la sintaxis correcta de un código fiscal; +* **Dirección de Internet**: comprueba si el parámetro es una dirección de Internet. + +.. |imagen46| imagen:: media/image45.png +:ancho: 30 + +Si el administrador necesita crear reglas de validación adicionales, puede hacer clic en |image46| para abrir la interfaz de creación de reglas. Aquí puede definir una regla de validación personalizada utilizando las opciones de verificación disponibles: + +* **Fecha**: aquí puede establecer un tipo de formato personalizado de fecha; +* **Expresión regular**: para establecer una regla de validación de expresiones regulares; +* **Longitud máx./mín.**: le permite establecer la longitud máxima y/o mínima de los parámetros de caracteres; +* **Gama**: para establecer un rango que el valor de los parámetros debe satisfacer; +* **Decimal**: para establecer decimales máximos para los parámetros. + +Creación de un controlador analítico + +``` + +As explained at the beginning of this section, analytical drivers use information about users, their roles and profiles to filter data returned by their associated LOVs. Users, roles and profiles must have been already defined in the project context so that they are available to the driver. + +.. _analyticaldrivermanagbehav: +.. figure:: media/image52.png + + Analytical Driver Management. + +To create a driver, select Behavioural Model > Analytical Drivers Management from the developer menu. Here, you will see the entire list of available drivers. For each driver, the list shows unique label, description and type. To explore details the user must just select one menu item from the list and they will appear in the half right side, as shown in the figure above. Otherwise to delete one analytical driver the user must use the icon |image48| available at the end of each row of the list. Notice that you cannot delete a driver if a document is currently using it. + +.. |image48| image:: media/image44.png + :width: 30 + +To create a new driver, click on |image49| at the top right corner. The driver creation interface will open. At first execution only the upper part of the window is visible, as shown in the figure below. The upper part is the **Detail** section, where you can set the label, name and description. Choose the type between Date, String or Number depending on the type of expected data. Select Functional or Temporal if the driver is used by an end user or a scheduler, respectively. A click on the save botton, enabled as soon as the form is filled in, will save the driver and let the section below appear. + +.. |image49| image:: media/image45.png + :width: 30 + +.. _drivercrationbehav: +.. figure:: media/image53.png + + Driver creation. + +In the Analytical Driver Use Mode Details section, one or more LOVs are linked to the current driver, as well as roles and checks are assigned via the so-called *use modes*. + +To associate LOVs to the driver, switch to the “Analytical Driver Use Mode Details” tab. Here the user must set label and name of that specific use mode, the kind of input among **LOV input**, **Manual input** and **Map input**, as shown in below. + +.. figure:: media/image54.png + + Detail panel of LOV creation, second step. + +The first type allows the user to pick values from a previously defined LOV. When selecting this option the interface spread out the configuration panel where the user is asked to select a LOV from the list and a **Modality**. The latter defines how values are displayed and selectable when executing the document. In fact the user can choose among: + +- **Select from list**: all admissible values will be displayed directly within the drivers panel; +- **Select from popup window**: user will be able to select between admissible values by a lookup table displayed within a popup window; +- **Select from tree**: conceived for hierarchical LOVs, lets the users navigate the values in a hierarchical way; +- **Select from combobox**: the driver will look like a drop down menu. + +The second kind of input expects the user to type manually the value. Otherwise the third opens a map from which the user must select one or more regions accordingly to the layer property. When selecting this option the interface spread out the configuration panel where the user is asked to choose a layer and the layer property. More details are supplied in next sections for this kind of input. + +Moreover the user can add default values (namely values that will be passed to the document at its first execution) using the dedicated area. Here it is possible to pick default values from another LOV or to pick the first or the latter value of the current LOV (if the LOV input type was selected). + +In case of Manual Input Date the user can specify a maximum value driven by a LOV: + +.. figure:: media/image57.png + + Detail panel of LOV creation, specification of a maximum value. + +During execution of a document, the date picker will be limited by that value: + +.. figure:: media/image58.png + + Detail of a date picker for a date parameter with maximum value specified. + +.. note:: + **Analytical driver of type Manual Input Date with a default value and/or max value** + + In the case you want to use an analytical driver of type Manual Input Date with a particular date as default value and/or a maximum value, you have to use a particular syntax for the LOVs query. See the note *Create a LOV for the default value of an analytical driver of type Manual Input Date* in the section *Creating a List Of Value* for more details. + +.. note:: + **Analytical driver with hierarchical LOV and default LOV** + + In the case you want to use an analytical driver with a hierarchical LOV and a default LOV the latter need to be hierarchical too. For more details see *Create a LOV for the default value of an analytical driver with a hierarchical LOV* note in the section *Creating a List Of Value*. + +At the bottom of the page the user must associate roles to the “use mode”. This action is mandatory. The user connects the user’s roles that he/she wants to be allowed to see a certain list of values or certain regions or be able to type values at his/her convenience. + +Therefore, since an admin user can decide to separate values according to the other users’ roles, the analytical driver definition allows to configure different use mode. We can also set validation checks if needed. Then it is sufficient to save each use mode and click on **new use mode** to set a new one. We repeat the same procedure for all the use modes. Each use mode is represented in a separate tab. We will go deeper into this at the end of the section. + +All the selections can be multi-valued, but note that this option has to be set directly on the document detail during analytical driver +association. + +Creating an analytical driver for a spatial filter +``` + +En la sección anterior explicamos cómo configurar un controlador y cómo se puede vincular a diferentes tipos de entradas. En esta parte nos detenemos en la posibilidad de definir un controlador analítico espacial. Haciendo referencia a la siguiente figura, notamos que para configurar el driver geográfico debemos seleccionar el **entrada de mapa** opción: aquí, expandiendo el cuadro combinado, elige la capa sobre la que actuará el filtro. Es necesario que la capa haya sido previamente creada y cargada en Knowage **Catálogo de capas**. A continuación, es obligatorio especificar el nombre de la propiedad de la geometría en uso utilizando el cuadro de texto manual justo debajo. Recuerde que el nombre de la propiedad debe ser exactamente el mismo, por lo tanto, respete la mayúscula y la minúscula de la cadena. + +.. \_spatialanalyticdrivsett: +.. figura:: media/image55.png + + Spatial analytical driver settings. + +Estos pocos pasos impedirán que el controlador analítico espacial se asocie a un documento y se utilice para establecer un filtro espacial. + +Modos de uso analíticos del conductor + +``` + +Sometimes the same analytical driver (i.e., the same concept, like the concept of product brand) should display different values according to the user that is executing it. + +Suppose you have a report on sales and costs like the one in the first figure of this chapter and you want to add to it the possibility to filter also on product brands. If you load the report as the general manager, you should choose between all the possible product brands in the corresponding parameter. If instead you load it as, for instance, the food manager, then you should be able to filter only on product brands related to the Food family. + +In order to do this, let us focus again on the definition of the LOV and check that the already defined use mode ``All Brands`` is associated to the correct role ``general_manager``. Here you can add a second tab, called for instance ``Profiled_Brands``, and associate it to the role ``product_manager``. This is because the food manager user has ``product_manager`` role with profile attribute ``pr_family = Food``. + +Finally, we choose the second LOV created, the one returning only those brands that belong to a specific family (see the code example in section Parametrizing LOVs). The family is selected by checking the value of the family attribute in the user profile. + +Notice that here you can also choose a different type of display mode for the LOV. In other terms, different use modes correspond not only to different LOVs, but also to (possibly) different display mode (pop-up windows, combobox, ...). For instance, you can select a combobox display mode for the All Brands use mode and the pop up window display mode for the Profiled_Brands use mode. + +Once you have saved the LOV, just log out from Knowage and log in with a different user role, i.e. as a general manager, food manager and drink manager. Executing your report on sales and costs you can now notice the differences on the values and on the display mode of the Product Brand parameters according to the different users. Notice that, for food manager and drink manager, the parameters are always displayed as a pop-up window, while for the general manager also the display mode of the parameter varies. + +.. figure:: media/image56.png + + Behavioural Model Schema. + +Behavioural Model Lineage +~~~~~~~~~~~~~~~~~~~~~~~~~ + +It is possible to show a summary of the links between the LOVs, the analytical driver and the documents by selecting **Behavioural Model** > **Behavioural Model Lineage**. + +.. figure:: media/lineage.png + + Behavioural Model Lineage. + +The entire list of available LOVs, analytical driver and documents appears, as shown in figure below. + +.. figure:: media/lineage2.png + + List of LOVs, analytical driver and documents. + +By selecting one LOV or Analytical Driver or Documents the other will refresh showing only the elements associated with the selection done. To come back to the original situation click the refresh button on the top right corner. +``` diff --git a/functionalities-guide/birt-reporting/index.es.rst b/functionalities-guide/birt-reporting/index.es.rst new file mode 100644 index 00000000..c5aec02c --- /dev/null +++ b/functionalities-guide/birt-reporting/index.es.rst @@ -0,0 +1,421 @@ +# Informes BIRT + +Los informes representan el tipo más popular de análisis de negocios. De hecho, permiten la visualización de datos de forma estructurada y en consecuencia con formatos predefinidos. Las principales características de un informe son: + +* combinación de datos numéricos (tablas, listas, tablas cruzadas), gráficos e imágenes; +* diseño estático y perfecto para píxeles; +* salida multipágina y multiformato (PDF, HTML, DOC, etc.); +* organización de los datos por grupos y secciones; +* uso universal (resumen, detalle, analítico u operativo); +* ser adecuado para la producción y distribución fuera de línea (ejecución programada); +* facilidad de uso. + +Por estas razones, los informes suelen tener un nivel generalizado de uso: son utilizados por los desarrolladores para realizar análisis sintéticos y detallados, teniendo un nivel de dificultad particularmente bajo. + +BIRT, acrónimo de Business Intelligence and Reporting Tools, es una plataforma tecnológica de código abierto utilizada para crear visualizaciones e informes de datos. En la siguiente figura puede ver un ejemplo de informe BIRT. + +.. figura:: media/image327.png + + Example of a BIRT report. + +Knowage Studio contiene birt designer, mientras que Knowage Server contiene el motor de tiempo de ejecución. Una plantilla BIRT consiste en un archivo de texto XML con la extensión .rptdesign que es generada automáticamente por la plataforma Eclipse incrustada en Knowage Studio. Puede ser modificado manualmente por usuarios muy expertos aunque no sea una práctica recomendada. En este manual entraremos en detalles sobre cómo desarrollar un informe BIRT, desde su implementación dentro del Knowage Studio hasta su visualización dentro del Knowage Server. Todas las funcionalidades estándar de BIRT están disponibles en Studio, pero para obtener una visión general completa de las herramientas de informes de BIRT y una guía detallada para desarrolladores, el lector también puede consultar la documentación oficial en ``\_ + +## Introducción a Knowage Studio + +Knowage Studio es el entorno de desarrollo basado en Eclipse. Permite al desarrollador diseñar y modificar algunos documentos analíticos, por ejemplo, informes y cuadros de mando. Este módulo apoya al desarrollador en el diseño de documentos, así como durante los procesos de instalación y prueba, directamente en Knowage Server. La interacción entre estos dos componentes es posible gracias al módulo Knowage SDK. Los usuarios pueden mostrar la lista de documentos analíticos que están disponibles en el servidor y descargarlos, con el fin de modificarlos en su propio ordenador. + +Permite construir un proyecto de Knowage dentro de Eclipse, a través del cual los usuarios pueden crear nuevos documentos analíticos. También integra las herramientas necesarias para crear informes Jasper y BIRT. + +Para instalar Knowage Studio, primero compruebe que su entorno cumple los siguientes requisitos previos: + +* tiene un JDK 1.7.x ya instalado; +* tiene la variable JAVA_HOME ya establecida; +* tiene un sistema operativo certificado (Windows, Linux, Unix son generalmente aceptados). La lista de entornos certificados depende principalmente de los soportados por Eclipse. Consulte las notas de la versión de Knowage Studio para averiguar la versión de Eclipse incluida en cada paquete publicado. + +Si es así, el segundo paso es descargar el paquete adecuado desde su área personal en el sitio web de Knowage. + +En este punto, solo tienes que descomprimir el paquete descargado bajo una carpeta, teniendo un KnowageStudio\_** subcarpeta. Aquí puedes encontrar y ejecutar un **KnowageStudio.exe** o **Knowage.sh** para iniciar y seleccionar el espacio de trabajo preferido. + +El espacio de trabajo seleccionado funciona como un repositorio local para todos los objetos desarrollados (informes, gráficos, cabinas, etc.). Sin embargo, los documentos no son visibles ni reutilizables por otros usuarios hasta que se publican en Knowage Server. + +.. advertencia:: + + **Connection between Server and Studio** + + Once Knowage Studio has been configured, connect it to Knowage Server. This will be the deployment environment to provide end-users with all certified objects. The main steps to set the connection are: + + - select the Knowage perspective; + - create a Knowage project; + - set Knowage Server connections. + + These points will be described in the following. + +En la primera ejecución de Knowage Studio, aparece una página de bienvenida. + +El primer paso es crear un proyecto de Knowage seleccionando el icono de Knowage de la siguiente figura en la barra de herramientas ubicada en la parte superior de la página. + +.. figura:: media/image328.png + + New Knowage project icon. + +Una vez creado el proyecto, aparece un árbol de carpetas estándar. Las carpetas predefinidas son: + +* **Análisis de Negocio:** contiene todos los documentos desarrollados (informes, gráficos, cabinas, etc.) que se pueden cargar o descargar desde Knowage Server. Esta carpeta se puede estructurar con subcarpetas, para organizar libremente los propios documentos; +* **Carpetas privadas:** contienen la documentación personal o del proyecto de los usuarios. Esta carpeta puede ser administrada libremente por el usuario; +* **Recursos:** contienen todos los recursos técnicos utilizados en el proyecto (es decir, la referencia a un Servidor Knowage). + +Ahora puede configurar referencias a uno o más servidores de Knowage. En otras palabras, cada usuario puede trabajar para muchos proyectos que pueden ser: + +* alojado en diferentes servidores +* alojado en el mismo servidor con diferentes cuentas de usuario. + +Para definir una conexión de servidor, haga clic en el botón **Nuevo servidor** punto de la **Servidor** menú contextual. + +.. figura:: media/image329.png + + New Data Source connection. + +Un formulario le pedirá: + +* **Nombre del servidor:** un nombre lógico para identificar el servidor. El nombre se usa solo en el espacio de trabajo local y no tiene relación con el físico. +* **URL:** la url http donde el servidor está alojado y accesible. +* **Usuario:** el usuario que se autentica en Knowage Server, estableciendo sus derechos de acceso en términos de qué tipo de operaciones puede hacer (cargar y descargar un modelo o un conjunto de datos) y a qué partes del repositorio del servidor puede acceder. +* **Contraseña:** la contraseña de los usuarios. +* **Activo:** un indicador que indica el servidor activo. Es particularmente útil cuando el usuario está trabajando con varios servidores. El servidor activo indica que cada operación de carga y descarga hace referencia a esta instancia de Knowage Server. + +.. figura:: media/image330.png + + Server configuration wizard. + +.. advertencia:: + + **Connection to Knowage Server** + + If something in your network configuration has been changed from your first run of Knowage Studio, the connection test of Knowage Studio to the Server could fail. Most often this problem is due to the proxy settings in your Eclipse environment. If this is not the case, try to run Knowage Studio from the command line with the clean option (**Knowage.exe** clean) to reset working settings. + +¡En este punto, Knowage Studio está listo para trabajar! + +Definición de metadatos + +``` + +Each Knowage document (e.g., report, olap, chart, cockpit, etc.), has its own technical metadata stored in Knowage internal repository. The most relevant technical metadata describing document structure, content and behaviour are: + +- *Template*, which defines the document layout; +- *Data set*, which defines how data of each document should be read; +- *Analytical drivers*, which hook the template parameters to the graphical interface (at runtime), managing also the right form for parameters. + +Knowage Studio supports BI developers steering the implementation of the template for each analytical document through an easy graphical interface and simple wizards. Each document type has its own designer and manages the relation with data sources and data sets. Furthermore it enhances technical users with all the needed functionalities to design, develop, test, deploy and maintain Knowage analytical documents. As said above, each document is mainly associated to a template describing its layout and a data set defining how data will fill it. Knowage Studio assists the developer in writing these templates and/or data sets by means of a graphical user interface and of easy-to-use wizards. + +.. warning:: + **Datasets created with the Business Model** + + These data sets are often based on specific business models created through Knowage Meta. By the way, we will concentrate on how to manage the implementation of a data set using the BIRT Report designer available in Knowage + +We want to remark that an expert developer can work directly on the server, managing documents and data sets by hand, thanks to the web interface for administrators and developers. Usually, this procedure is faster when only small changes are required on already released documents, whereas the Studio is particularly useful when a developer works on new documents. + +The target users of the Studio module are: + +- BI developers, who define analytical documents and data sets to be released onto a remote Knowage Server +- administrators, who define or update analytical documents and data sets. + +In other words, Knowage Studio covers the development processes of more technical documents. On the other hand, high-level documents are created directly through Knowage Server, where a power user can access graphical designers without need to use the Studio, which requires more technical skills to manage the installation and configuration process. + +Data set definition +``` + +Cada tipo de documento tiene su propia forma de definir cómo obtener datos de un origen de datos interno, de acuerdo con una definición de conjunto de datos. Esto permite que el documento acceda directamente al RDBMS, a través del script de carga SQL, que se puede codificar dentro de la plantilla o externamente (es decir, almacenado como recurso de Knowage Server), pero sin ninguna abstracción de las fuentes de datos. + +## Desarrollo de un informe BIRT + +Para crear un nuevo documento, haga clic con el botón derecho en el botón **Análisis de Negocio** y, para comenzar, elija entre informe y panel. En la siguiente figura elegiremos **Informe con Birt** y dejar la otra opción para el siguiente capítulo. + +.. figura:: media/image331.png + + New document creation. + +Una vez que se diseña el documento, se almacena como un archivo local, marcado con un icono y una extensión de archivo específica: + +* **.sbidoccomp:** plantillas de documento para el panel que utilizan el motor ComposedDocument; +* **.rptdesign:** plantilla de documento para informes que utilizan el motor BIRT. + +En nuestro caso, obtendremos un archivo .rptdesign. Un doble clic en uno de estos archivos permite abrir la plantilla de documento, con su editor gráfico relacionado. + +El diseño y la implementación de un informe BIRT incluye los siguientes pasos: + +* crear el documento vacío; +* cambiar a la perspectiva del diseñador de informes; +* crear el origen de datos; +* crear el conjunto de datos; +* diseñar el informe a través de la interfaz gráfica; +* implementar el informe en el servidor. + +Para crear un nuevo informe BIRT, como se acaba de anticipar, haga clic con el botón derecho en el botón **Análisis de Negocio** y seleccione **Informe** > **Informe con BIRT**. Esto abrirá un editor donde puede elegir el nombre de su documento. El nuevo documento se creará bajo el **Análisis de Negocio** carpeta. + +Haga doble clic en él para abrir el editor. En este punto, todavía estás trabajando en la perspectiva del Knowage. Para diseñar el informe, cambie a la perspectiva real del diseñador BIRT. Haga clic en el icono de perspectiva del editor de Eclipse y seleccione el Diseñador de informes entre las perspectivas disponibles, como se muestra en la figura a continuación. + +.. figura:: media/image332.png + + Change perspective. + +Los siguientes pasos son la creación de una fuente de datos y de un conjunto de datos. Como se describió anteriormente en la sección Definición de conjunto de datos, Knowage Studio permite el desarrollo de documentos analíticos utilizando conjuntos de datos internos o externos. En este ejemplo específico, mostraremos cómo crear un informe con un conjunto de datos interno. En primer lugar, en el caso de un conjunto de datos interno, defina un **Origen de datos JDBC**. + +Haga clic derecho en el botón derecho **Origen de datos** y seleccione el origen de datos correspondiente. Se abrirá un editor emergente que le indicará la configuración de conexión: + +* **Clase de conductor** +* **URL de la base de datos** +* **Nombre de usuario** y **contraseña** + +Tenga en cuenta que el Studio utilizará estos parámetros de configuración para conectarse a la base de datos y permitir que el informe se ejecute localmente (es decir, dentro del Studio). Asegúrese de que la base de datos establecida en el servidor comparte el mismo esquema del definido en el estudio. + +Dado que está estableciendo una referencia local a una base de datos dentro del informe, recuerde establecer una información adicional: esto permitirá a Knowage Server ejecutar correctamente el informe, conectándose al origen de datos al que se hace referencia dentro del servidor y no dentro del informe. Básicamente, debe decirle al servidor que invalide la configuración de la fuente de datos. Por lo tanto, agregue un parámetro al informe, llamado connectionName, haga clic con el botón derecho en el elemento de menú "Parámetros del informe" y seleccione "Nuevo parámetro". Rellene el formulario como se sugiere a continuación. + +.. figura:: media/image333.png + + Adding connectionName Parameter. + +Luego vaya a **Enlace de propiedades** en el editor de orígenes de datos y establezca la propiedad JNDI URL en el valor del parámetro connectionName, como se muestra a continuación. + +.. figura:: media/image334.png + + Setting the connectionName parameter in the Data Source editor + +.. advertencia:: + + **JNDI URL** + + Do not forget to define the connectionName parameter in your BIRT report and set the JNDI URL accordingly. Without these settings your BIRT report may be unable to access data once it is deployed on the server. In addition, if database and connection properties change, you need to change the connection properties only in Knowage server. + +Una vez configurado el origen de datos, puede continuar con la creación de un conjunto de datos. Por lo tanto, haga clic con el botón derecho en el botón **Conjunto de datos** y seleccione **Nuevo conjunto de datos**. En la siguiente ventana, seleccione el origen de datos, el tipo de consulta y asigne un nombre al conjunto de datos, como se muestra a continuación. El ámbito de este nombre se limita al informe, ya que estamos definiendo un conjunto de datos interno. + +.. figura:: media/image335.png + + Dataset definition. + +Ahora puede definir su conjunto de datos escribiendo la consulta SQL en el editor y probando los resultados (consulte :numref:`datasetedtwithprw`). En cualquier momento, puede modificar el conjunto de datos haciendo clic en él, lo que volverá a abrir el editor de consultas. + +Diseñemos un informe muy simple, que contenga una tabla que muestre los datos del conjunto de datos definido. La forma más fácil de crear una tabla a partir de un conjunto de datos es arrastrar y soltar el conjunto de datos desde el menú del árbol en el área del editor. + +La forma más genérica, que se aplica a todos los elementos gráficos, consiste en cambiar a la **Paleta** en el panel izquierdo, manteniendo al diseñador en el panel central. Arrastre y suelte la tabla en el área del editor. Tenga en cuenta que esto se puede hacer con todos los demás elementos enumerados en la paleta. En este punto, puede editar la tabla (así como cualquier otro elemento gráfico del informe) utilizando el **Editor de propiedades** debajo del área del editor. + +Al desarrollar un informe, es particularmente útil probarlo regularmente. Para ello, haga clic en el botón **Vista previa** debajo del área del editor. Para volver al editor, simplemente haga clic en el botón **Diseño** pestaña. En **Página maestra** , puede establecer las dimensiones y el diseño del informe; el **Guión** tab admite funcionalidades avanzadas de scripting; por último, el **Origen XML** muestra el código fuente editable del informe. + +Al desarrollar un informe, es particularmente útil probarlo regularmente. Con este fin, haga clic en la pestaña Vista previa debajo del área del editor. Para volver al editor, simplemente haga clic en la pestaña Diseño. En la pestaña Página maestra, puede establecer las dimensiones y el diseño del informe; la ficha Script admite funcionalidades avanzadas de scripting; por último, la ficha Origen XML muestra el código fuente editable del informe. + +.. \_datasetedtwithprw: +.. figura:: media/image336.png + + Dataset editor, with preview. + +.. figura:: media/image337.png + + BIRT Property Editor. + +Una vez finalizado el informe, puede implementarlo en Knowage Server. + +.. nota:: +**Implementación en Knowage Server** + + Please refer to the section *Download and Deploy* in this chapter to find out more on report deployment. + +El diseñador de informes BIRT permite la creación de informes complejos, con diferentes elementos gráficos como pestañas cruzadas, gráficos, imágenes y diferentes áreas de texto. En esta sección no proporcionamos ningún detalle sobre el desarrollo gráfico, pero nos centramos en aspectos específicos de Knowage BIRT Report Engine. + +.. nota:: +**Diseñador BIRT** + + For a detailed explanation of report design, pleas refer to BIRT documentation at www.eclipse.org/birt/. + +Uso de un conjunto de datos externo + +``` + +In the afore-described example, we built a report using an internal dataset, i.e., a dataset defined within the report. This has two main implications. First, the dataset is not visible outside the report execution: for example, it cannot be directly reused by other reports. Second, an internal dataset is always defined as a SQL query and it cannot take advantage of Knowage business model abstraction. For these reasons, Knowage allows the definition of external datasets in reports. An external dataset is defined in Knowage Server and, as a consequence, it is visible to all documents on the server (i.e., it can be used by any of them, if properly linked to the document). External datasets can either be SQL datasets or QbE datasets, that is, datasets defined by queries over a business model. + +An external dataset can be included into any BIRT report by downloading it from a Knowage Server. Specifically: + +- define a Knowage Server datasource; +- download a dataset from the Knowage Server datasource. + +We always start by right-clicking on the **Data Source** item. Select **Knowage Server Data Source** and set the appropriate input configuration: + +- **Server URL** +- **Username** and **password** used to log into the Server (e.g., biadmin). + +After filling in the configuration fields, test the connection and save it. The new data source will appear in the left tree menu. Instead of connecting to a database via a JDBC driver, connect to the server as the source of data. Obviously, the actual data source and dataset must have previously been defined on the Server. + +To select the dataset, click on **New Data Set** as above, but this time select the **Knowage Data Source** that you have just defined. Now, instead of choosing a new name for the dataset, insert the correct label of the dataset that you want to import from the Server. If the label is correct, the dataset will be imported in the report by clicking on **Finish**. Notice that the imported dataset may be a SQL or a QbE one. Since both types of datasets are stored in the same repository by Knowage Server, we are enabled to use any BM query in the development of a report. + +.. warning:: + + **Use of BM queries in report development.** + + The ideal use of a business model is to define queries over the BM via Knowage Meta, deploy them on Knowage Server and reuse them on Knowage Studio as external datasets. + +Adding parameters to reports +``` + +La mayoría de las veces los informes muestran análisis de datos que dependen de parámetros variables, como el tiempo, el lugar y el tipo. Knowage Studio permite al diseñador agregar parámetros a un informe y vincularlos a controladores analíticos definidos en Knowage Server. + +Para usar estos parámetros, primero debe agregarlos a su informe. Haga clic derecho en **Parámetros del informe** en el panel de árbol y seleccione **Nuevo parámetro**. Aquí puede establecer el tipo de datos y elegir un nombre para su parámetro. + +.. advertencia:: + + **Parameters URI** + + Be careful when assigning a name to a parameter inside a report. This name must correspond to the parameters URI when you deploy the document on Knowage Server. + +Una vez que haya definido todos los parámetros, abra el conjunto de datos (o cree uno nuevo). Los parámetros se identifican mediante un signo de interrogación **?** . Para cada uno **?** que inserte en su consulta, debe establecer el vínculo correspondiente en el cuadro de diálogo **Parámetros** : esto permitirá la sustitución de parámetros en el momento de la ejecución del informe. + +.. figura:: media/image338.png + + Creation of a new parameter in a BIRT report. + +Tenga en cuenta que debe establecer un vínculo para cada signo de interrogación como se muestra a continuación, incluso si el mismo parámetro se produce varias veces en la misma consulta. + +.. \_insrtprmintodtsetdef: +.. figura:: media/image339.png + + Insert parameters into the dataset definition. + +.. advertencia:: + + **Transfer reports from Studio to Server and vice versa** + + We saw that developers can use Knowage Studio deployment service to easily register the report with its template on Knowage Server. Alternatively, any valid BIRT template (developed with or without Knowage Studio) can be directly uploaded in Knowage Server using the web interface for document management. + +Los parámetros también se pueden usar dentro de algunos elementos gráficos, como el texto dinámico, con la siguiente sintaxis: + +.. code-block:: javascript +:linenos: +:caption: Sintaxis de parámetros + + params[name_of_parameter].value + +## Descargar e implementar + +Para modificar un documento ya implementado, primero descargue la plantilla relacionada desde el repositorio de Knowage Server. + +Haga clic con el botón derecho en el botón **Análisis de Negocio** o en una de sus subcarpetas. En el menú contextual, seleccione el botón **Descargar** opción. En este punto, aparece el árbol de funcionalidades, que le permite elegir los documentos que se descargarán. + +Estos documentos estarán disponibles en la carpeta local que haya seleccionado previamente. Los detalles del documento (es decir, etiqueta, descripción, estado, motor y parámetros) se almacenan como metadatos en el repositorio local. Los metadatos se pueden actualizar desde el servidor haciendo clic en el botón **Actualizar** en el botón **Conocimiento** > **Metadatos del documento** de la ficha **Propiedades** sección. Para abrir Propiedades, haga clic con el botón secundario en el elemento del documento y seleccione **Propiedades**. + +De manera similar, después de una actualización del documento, la opción Implementar del mismo menú envía la nueva plantilla al servidor, lista para su uso. + +Otra situación posible es cuando el diseñador crea una nueva plantilla desde cero y la implementa en el servidor. En la primera implementación, se crea un vínculo entre la plantilla y un documento en el servidor. Durará hasta que se elimine el documento en el servidor o se modifique su etiqueta. En esos casos, deberá volver a implementar la plantilla desde Studio. + +Para implementar una plantilla, haga clic con el botón secundario y seleccione **Desplegar**. Se le pedirá un formulario para metadatos básicos en el nuevo documento. Los datos de entrada requeridos y/o rellenados previamente pueden cambiar según el tipo de documento. Sin embargo, generalmente incluyen: + +* **Etiqueta:** etiqueta libre como código corto; +* **Nombre:** nombre del documento; +* **Descripción:** descripción larga; +* **Tipo:** tipo de documento (informe, gráfico, cabina, etc.); +* **Conjunto de datos:** el conjunto de datos ya desplegado para documentos que utilizan documentos externos; +* **Fuente de datos:** la referencia a la fuente de datos que se utilizará en SpagoBI Server para documentos que tienen un conjunto de datos interno, con el fin de trabajar con la fuente oficial en lugar de RDBMS local o en funcionamiento; +* **Estado:** el estado inicial del documento (desarrollo, prueba, liberación, suspensión) de acuerdo con su política de gestión del ciclo de vida; +* **Actualizar segundos:** el tiempo de actualización automática; +* **Posición:** la carpeta en el repositorio remoto de Knowage Server donde se implementan los documentos, estableciendo indirectamente quién puede usarlo y su primer nivel de autorización. + +.. advertencia:: + +``` + **Analytical documents** + + The described form sets basic metadata, generally managed as technical metadata on Knowage Server. + +``` + +Estos detalles del documento se almacenan como metadatos en el repositorio local y se utilizan para registrarlo también en el repositorio central del servidor. Para ver sus valores locales, seleccione el botón **Propiedades** en el menú contextual del documento y elija **Conocimiento**. + +Directamente desde allí, los metadatos locales se pueden actualizar en cualquier momento en el servidor activo, simplemente presionando el botón **Actualizar metadatos en active server** botón. + +## Navegación cruzada para informes BIRT + +Una característica poderosa de los documentos analíticos de Knowage es la navegación cruzada, es decir, la capacidad de navegar por los documentos de una manera similar a un navegador siguiendo los flujos de datos lógicos. Aunque la crossnavigation se proporciona uniformemente en todos los documentos ejecutados en Knowage Server, cada tipo de documento tiene su propia modalidad para establecer el enlace que apunta a otro documento. + +Observe que el puntero puede hacer referencia a cualquier documento de Knowage, independientemente del documento de origen. Por ejemplo, un informe BIRT puede apuntar a un gráfico, una consola, una geografía o cualquier otro documento analítico. + +En Knowage existen dos tipologías principales de navegación cruzada: *interno* y *externo*. + +*Navegación cruzada interna* actualiza una o más áreas de un documento haciendo clic en una serie, un texto, una imagen o, en general, en un +elemento seleccionado del documento. + +*Navegación cruzada externa* abre otro documento haciendo clic en un elemento del documento principal, permitiendo de esta manera la definición de una "ruta de navegación" a lo largo de los documentos analíticos (por lo general, desde información muy general y agregada hasta la información más detallada y específica)). De hecho, puede agregar la navegación cruzada también a un documento alcanzado por la navegación cruzada. Esto puede ser útil para profundizar en un análisis, ya que cada paso de navegación cruzada podría ser una visualización más profunda de los datos que se muestran en el documento inicial. + +Obviamente, es posible asociar más de una navegación cruzada a un solo documento. Significa que al hacer clic en diferentes elementos del mismo documento, el usuario puede ser dirigido a diferentes documentos. + +Para permitir la navegación cruzada externa en un informe BIRT, debe agregar un hipervínculo al elemento en el que desea que se pueda hacer clic mediante el botón **Propiedades** de Knowage Studio. La mayoría de los elementos de informe pueden hospedar un hipervínculo. Por ejemplo, agreguemos un hipervínculo a una celda de la tabla. + +Haga clic en la celda de la tabla y seleccione el botón **Hiperenlace** en el **Propiedades** pestaña. Al hacer clic en Editar, el editor de hipervínculos se abrirá y mostrará tres campos de entrada: + +* **Ubicación:** escriba aquí el URI, +* **Blanco:** seleccione Self, +* **Información sobre herramientas.** escriba el texto que desea que aparezca en el enlace, como se muestra en la siguiente figura a continuación. + +.. figura:: media/image340.png + + Hyperlink editor. + +Para editar la ubicación, haga clic en el botón desplegable derecho y seleccione la sintaxis de JavaScript. Esto abrirá el editor de JavaScript BIRT. Aquí debe escribir la función javascript "javascript:parent.execExternalCrossNavigation" pasando argumentos JSON como ParName: string, null y string. + +En la sintaxis de Cross Navigation damos una idea de cómo debe ser la sintaxis: + +.. \_crossnavsyntax: +.. code-block:: javascript +:linenos: +:caption: Sintaxis de navegación cruzada. + + "javascript:parent.execExternalCrossNavigation("+ + "{OUT_PAR:'"+params["par_period"].value+"'"+ + ",OUT_STRING:'"+string_text+"'"+ + ",OUT_NUM:"+numberX+ + ",OUT_ManualSTRING:'foo'"+ + ",OUT_ARRAY:['A','B','5']}"+ + ",null,"+ + "'Cross_Navigation_Name');" + +.. advertencia:: + +``` +**Type the right cross navigation name** + + It is important to underline that the "Cross_Navigation_Name" of Cross Navigation syntax is the cross navigation name related to the document and set using the "Cross Navigation Definition" feature we described in *Analytical Document* Chapter, *Cross Navigation* Section. + +``` + +Será necesario escribir el nombre de navegación cruzada correcto relacionado con el documento tal como se define utilizando la configuración "Herramienta" del servidor Knowage y definir esos parámetros (OUT_PAR, OUT_STRING, etc.) como parámetros de salida en el documento desplegado en el servidor (consulte *Documento analítico* Capítulo *Navegación cruzada* Sección). + +Tenga en cuenta que la sintaxis de la cadena es fija, mientras que debe asignar valores a los parámetros que se pasarán al documento de destino. El editor de JavaScript le ayuda a insertar enlaces de columna de conjunto de datos, como se muestra en la figura siguiente, y a informar de los parámetros automáticamente. + +.. figura:: media/image342.png + + Column bindings. + +Para administrar parámetros de múltiples valores es suficiente enumerar todos los valores entre corchetes separándolos con comas, como se informa en el código anterior. Más específicamente, la matriz debe contener valores del mismo tipo. Por ejemplo: + +.. code-block:: javascript +:linenos: + + OUT_SeveralNames:['Michael','Paul','Sophia'] + +o + +.. code-block:: javascript +:linenos: + + OUT_SeveralNames:[5,9,31938] + +Finalmente, es posible establecer una especie de navegación "multi"-cruzada si, por ejemplo, el documento de salida está relacionado con más de un documento a través de la Definición de navegación cruzada. Supongamos que el documento de origen va a un documento de destino y el nombre de la navegación es "CrossNav1" y simultáneamente el documento de origen va a un segundo documento de destino y el nombre de la navegación es "CrossNav2". Si en la función JavaScript de *Sintaxis de navegación cruzada* código el "Cross_Navigation_Name" se deja vacío como en el código siguiente, cuando el usuario hace clic en el objeto para el que se ha habilitado la navegación se abre una ventana emergente pidiendo al usuario que elija entre la navegación "CrossNav1" o la "CrossNav2". Este procedimiento permite al usuario tener una navegación más de una posible a partir del mismo objeto. + +.. \_crossnavsyntax2: +.. code-block:: javascript +:linenos: +:caption: Sintaxis de navegación cruzada + + "javascript:parent.execExternalCrossNavigation("+ + "{OUT_PAR:'"+params["par_period"].value+"'"+ + ",OUT_STRING:'"+string_text+"'"+ + ",OUT_NUM:"+numberX+ + ",OUT_ManualSTRING:'foo'"+ + ",OUT_ARRAY:['A','B','5']}"+ + ",null,"+ + "'');" diff --git a/functionalities-guide/chart/index.es.rst b/functionalities-guide/chart/index.es.rst new file mode 100644 index 00000000..0cf11948 --- /dev/null +++ b/functionalities-guide/chart/index.es.rst @@ -0,0 +1,636 @@ +# Gráfico + +Los gráficos son el método más adoptado en la presentación de datos de BI, ya que permiten una percepción inmediata de un fenómeno y son fácilmente comprensibles. Enfocados en una impresión visual más que en una conferencia puntual de valores, son especialmente adecuados para mostrar tendencias y comparaciones. + +Por estas razones, los gráficos ganan un nivel generalizado de uso y pueden ser utilizados por cualquier persona para realizar análisis sintéticos y detallados. +Knowage proporciona un motor de gráficos para crear varios tipos de gráficos, que incluyen: + +* Barra +* Línea +* Pastel +* Sunburst +* Nube de palabras +* Mapa de árbol +* Paralelo +* Radar +* Esparcir +* Mapa de calor +* Acorde +* Calibre +* Burbuja + +## Mi primer gráfico + +Una vez que ingrese al entorno de Knowage como usuario final, ingrese el **Análisis** área bajo el **Área de trabajo** , haga clic en el botón **Crear análisis** y elija **Cabina**. + +.. importante:: +**Solo Enterprise Edition** + + Please note that this operation is available only in KnowageBD and KnowageSI. Using the KnowagePM license, only a technical user can create Cockpit document. + +Una vez abierta, la interfaz de la cabina es una página vacía con una barra de herramientas que contiene diferentes opciones, la segunda de las cuales es la **Agregar gráfico** característica. + +.. figura:: media/image90.png + + Add a chart to a cockpit. + +.. nota:: +**Cabina** + + The Cockpit Engine allows the user to self-build interactive cockpits through an intuitive and dynamic interface. Read more in *Cockpit* chapter. + +Haciendo clic en el botón **Agregar gráfico** , se le pedirá que elija entre algunos widgets disponibles. Elige el **Gráfico** uno y ahora entremos en detalles sobre cómo construir un gráfico desde cero. El editor del diseñador se divide en cuatro pestañas principales: **Conjunto de datos**, **Diseñador de motores de gráficos**, **Estilo**, **Cruz** y **Filtros**. Tan pronto como el usuario hace clic en el botón "Agregar gráfico", ingresa al editor de pestañas "Conjunto de datos". Aquí el usuario debe seleccionar, utilizando el icono "little plus" colocado justo al lado de la línea del cuadro combinado, un conjunto de datos. Luego, el usuario debe cambiar a la pestaña "Chart Engine Designer" y elegir un tipo de gráfico entre los disponibles, como se muestra en la figura a continuación. + +.. figura:: media/image91.png + + Chart editor. + +Después de elegir el tipo de gráfico apropiado, debe ir al **Estructura** página. Aquí es posible seleccionar las medidas y los atributos elegidos para el gráfico. + +.. \_chartstructure: +.. figura:: media/image92.png + + Chart structure. + +Haciendo clic en el botón **Configuración** página encontrará ocho bloques diferentes como puede ver en la figura a continuación. + +.. figura:: media/image93.png + + Chart configuration. + +En detalle, estos bloques se refieren a: + +* **Detalles genéricos**, como la orientación del gráfico, la familia y la fuente de tamaño. +* **Detalles del título y los subtítulos** +* **Sin mensaje de datos** donde es posible poner un mensaje donde los datos no están fundados. +* **Título de la leyenda** +* **Elementos de leyenda** +* **Paleta de colores** +* **Configuración avanzada de la serie** +* **Colores personalizados** + +Estos ocho bloques son comunes a todos los tipos de gráficos; de todos modos, algunos tipos de gráficos pueden tener bloques adicionales. + +El **Avanzado** contiene características adicionales, generalmente explotadas por un usuario experto. Aquí el usuario puede ver todas las propiedades configurables asociadas al gráfico: refleja las pestañas de propiedades que un usuario experto debe editar manualmente para generar una plantilla json. + +.. figura:: media/image94.png + + Chart Advanced Features. + +En las siguientes subsecciones, las funcionalidades disponibles de las pestañas Estructura, Configuración y Avanzadas se describen de una manera más específica. + +.. importante:: +**Solo Enterprise Edition** + + Please note that the "Advanced" tab is available only in Knowage Enterprise Edition. + +Estructura + +``` + +The “Structure” tab of the designer is the core of the Chart development. Here it is possible and mandatory to choose the measures and the attributes. When selected, the tab shows a two axes panel. The horizontal axis indicates the X-axis where you must choose one or more attributes. As well, the left axis is the Y-axis and here you must choose measures. You can also insert manually the axis title for both the X and the Y axis if the chart is configured to have axis titles. + +.. warning:: + **Chart type changemens may cause broke down** + + Before creating any chart, it is convenient to be sure of what kind of chart you want to develop. We stress that the user can change the chart type afterwards, but at the expense of a loss of just defined settings. + +In this section it’s possible to customize the labels of the axis, titleand grid style clicking on different buttons. With the arrow button, on the top of the Y-axis and X-axis, it’s possible to choose the axis configuration detail, the axis title configuration, the major and minor grid configuration (just for Y-axis) and ordering column (just for X-axis). With the pencil button opens a window on the right with the series configuration details where it’s possible to choose the aggregation way, the order type of the series, if the data will be shown e so on. Finally, with the strip cartoon button you can choose the features of the tooltip (font color, text alignment, ecc). If the chart in place does not allow the customization of the axes the specific button will be disabled or not visible. The Figure below will show in detail the three buttons above explained: + +.. figure:: media/9597.png + + From left to right: (a) Generic configuration axis (the specific arrow). (b) Generic configuration axis. + +.. figure:: media/image97.png + + Series style configuration. + +.. figure:: media/image98.png + + Series tooltip details. + +Configuration +``` + +El **Configuración** contiene opciones para definir el estilo genérico del gráfico. Aquí puede establecer las dimensiones del gráfico, el color de fondo, insertar el título y el subtítulo y definir su estilo, elegir la paleta de la serie, asociar un color específico a una serie o categoría en particular, agregar y configurar la leyenda. Las opciones enumeradas son un ejemplo de lo que puede configurar en la ficha. + +Tenga en cuenta que para los detalles de la paleta de colores puede usar uno que ya esté en la lista o puede elegir cualquier color insertando el código de color hexadecimal con el símbolo de hashtag. Esta es una característica muy útil para personalizar la salida. + +.. figura:: media/image99.png + + Color box editing. + +En concreto, en la versión 6.3, se ha introducido una nueva opción de configuración: el Custom Color. + +.. figura:: media/image200.png + + Custom Colors details. + +Con esta nueva opción es posible asignar un color específico a una categoría y/o serie en particular o a un valor particular de una categoría y/o serie. Mire la siguiente figura para ver un ejemplo. + +.. figura:: media/image201.png + + Custom Colors example. + +Para agregar un color personalizado, simplemente escriba el valor o nombre de la categoría / serie, seleccione un color con el color piker y luego haga clic en el botón más. En el ejemplo de la figura se le asigna un color para cada valor de la categoría 'QUARTER'. + +De hecho, las opciones disponibles en esta pestaña cambian de acuerdo con el gráfico seleccionado habilitando diferentes configuraciones. Consulte Tipos de gráficos en detalle para obtener una descripción detallada de las opciones específicas de cada gráfico. + +Opciones avanzadas + +``` + +The **Advanced** tab contains some advanced options to more customize the chart. Here it is possible, for example, to set the tooltip options, the widget dimensions, if the chart is stacking or not, the grouping type. + +.. figure:: media/image140.png + + Advanced tab. + +Down here are listed some of the most useful and new options. + +The **dataLabels** option can be found under the path VALUES -> SERIE -> 0 or another serie -> dataLabels. The option is available only for measures. Here it is possible to set the labels style such as the color, font family or font weight. + +.. figure:: media/image141.png + + dataLabels option. + +The **TOOLTIP** option allows to set the width and the radius of hte tooltip's border. + +The **plotBands** and **plotLines** options can be found under the path AXES_LIST -> AXIS -> 0 or another serie. With these options is possible to plot respectively bands and lines on the chart with fixed values and to set their style, like the line width and the line type or the band color. + +.. figure:: media/image142.png + + plotBands option. + +The **min** and **max** options are under the path AXES_LIST -> AXIS -> 0 or another serie. They are available only for series and allow to set the maximum and minimum axis value for the selected sere's axis. + +.. figure:: media/image143.png + + min and max options. + +Chart types in detail +------------------------- + +This section describes the different types of chart and how to create them within the **Chart Engine** of Knowage. + +Traditional charts +``` + +Knowage le permite crear los llamados gráficos tradicionales como barras, líneas, pasteles, radares y gráficos de dispersión de una manera elegante. + +Cada tipo de gráfico se basa en un conjunto de datos específico. A pesar de todo, hay algunas reglas generales que se pueden aplicar a esos gráficos "más simples" y comunes. El requisito mínimo es definir/tener un conjunto de datos con al menos una columna de atributo y una columna de medida. A continuación, puede seleccionar el tipo de gráfico que desea utilizar en el **Gráfico** sección; mientras tanto, utilizando el **Estructura** puede rellenar el cuadro de categoría con uno o más atributos (normalmente estos se colocarán en el eje X) y en el cuadro de serie con una o más medidas (normalmente se colocan como valores del eje Y). Consulte *Estructura del gráfico* figura como ejemplo. + +Una vez que haya seleccionado los atributos y las medidas, puede editar el estilo de serie y las configuraciones de estilo de eje como se explica en Mi primer gráfico. Luego vaya a **Configuración** para establecer la dimensión del gráfico, el título, la leyenda y elegir cómo asociar colores a la serie. + +Algunos gráficos están dotados de funciones de fecha y hora y agrupación. En particular, es posible habilitar las funciones de agrupación/división para **Barra** y **Línea** tablas. + +El usuario puede acceder a esas funciones simplemente haciendo clic en la "pequeña flecha" ubicada en el extremo derecho de la barra de categorías. + +.. figura:: media/image100.png + + Datetime and grouping function. + +Las funciones de agrupación solo se pueden implementar a través de categorías específicas y configuraciones de serie. Como se muestra en la figura siguiente, la función de agrupación no se puede aplicar con un solo atributo como categoría. Para permitir que se aplique la función, el usuario debe definir dos atributos como campos de categoría. + +.. figura:: media/image101.png + + Error alarm when enabling the grouping function. + +Además, el usuario puede usar las funciones de división para dividir una serie sobre la segunda o sobre la segunda categoría. + +Para dividir la primera serie sobre la segunda, recuerde que es necesario elegir solo un atributo como campo de categoría y dos medidas como valores de serie. La siguiente figura muestra un ejemplo. + +.. figura:: media/image102.png + + Split over second series. + +Mientras tanto, para dividir una medida en una segunda categoría, es obligatorio elegir exactamente dos atributos como campo de categoría y solo una medida como valor de serie, como se muestra en la figura a continuación. + +.. figura:: media/image103.png + + Split over second category. + +Además, en la ocurrencia de que el gráfico utiliza un atributo datetime como campo de categoría, el usuario puede mejorar la visualización aplicando la función datetime al formato de fecha personalizado. + +.. figura:: media/image104.png + + Datetime function usage. + +Para el gráfico de barras y líneas, puede agregar más de un contenedor para agregar series en **Estructura** sección. En ese caso tendrás en tu gráfico más de un eje para series. +En **Avanzado** sección que puede especificar para alinear estos ejes al valor 0 (cero). Es casilla de verificación **alignAxis** donde se comprueba significa que los ejes se alinearán con 0, y sin comprobar significa que no se alinearán. + +Para gráfico circular en el interior **Avanzado** puede establecer la configuración de su toolip: para mostrar/ocultar el valor absoluto y/o el porcentaje. Adentro **información sobre herramientas** propiedad del objeto serie se pueden encontrar properies **showAbsValueTooltip** y **showPercentageTooltip**. + +Gráfico de dispersión + +``` + +A scatter chart is a graphical representation of scattering phenomenon of data. It is useful when the user wants to underlight the density of data upon certain spots to the detriment of readability of single points. If you select a scatter chart in the **Configuration** section you will have Ticks and Lables Details instead of Advanced Series Configuration. Be carefull to fill in the **Scatter configuration** with the **Zoom type**, as showed below. + +.. figure:: media/image105.png + + Scatter Chart, ticks and labels details. + +You must check if you want that the values in the Y-axis start (or end) in the first (last) tick or in the first (last) value of the dataset and if you want that the last label of the category axis should be showed. + +Sunburst chart +``` + +El gráfico sunburst es un gráfico con un diseño radial que representa la estructura jerárquica de los datos que muestran un conjunto de anillos concéntricos. El círculo en el centro representa los nodos raíz, con la jerarquía moviéndose hacia afuera desde el centro. Las rebanadas en los anillos externos son hijos de la rebanada en el círculo interno, lo que significa que se encuentran dentro del barrido angular del círculo interno. El área de cada sector corresponde al valor del nodo. Incluso si los gráficos de rayos solares no son eficientes en cuanto al espacio, permiten al usuario representar jerarquías de una manera más inmediata y fascinante. + +Para crear un gráfico sunburst en Knowage solo tienes que seleccionar un dataset con al menos dos columnas de atributos que describan la jerarquía y al menos una columna de medida que indique el ancho de los segmentos. Un +El ejemplo de conjunto de datos para el gráfico sunburst se muestra en la tabla a continuación. + +.. \_exampleofdatsetsunburst: +.. table:: Ejemplo de conjunto de datos para el gráfico sunburst. +:widths: automático + +\+----------------------+----------------+------+ +| CATEGORÍA | SUBCATEGORÍA | UNIDAD | +\+======================+================+======+ +| Productos de panadería | aceite de cocina | 349 | +\+----------------------+----------------+------+ +| Productos de panadería | Salsas | 109 | +\+----------------------+----------------+------+ +| Productos de panadería | Especias | 290 | +\+----------------------+----------------+------+ +| Productos de panadería | | de azúcar 205 | +\+----------------------+----------------+------+ +| Productos de baño | | acondicionador 64 | +\+----------------------+----------------+------+ +| Productos de baño | Enjuague bucal | 159 | +\+----------------------+----------------+------+ +| Productos de baño | Champú | 254 | +\+----------------------+----------------+------+ +| Productos de baño | Cepillos de inodoro | 92 | +\+----------------------+----------------+------+ +| Productos de baño | Cepillos de dientes | 94 | +\+----------------------+----------------+------+ + +Una vez seleccionado el conjunto de datos y el tipo de gráfico, elija al menos dos atributos en el panel Eje X y una medida en el panel Eje Y como se muestra en la siguiente figura. + +.. figura:: media/image106.png + + Sunburst configuration. + +Luego haga clic en **Configuración**. Como puede ver, las características no son exactamente las mismas que el gráfico tradicional. Damos algunos consejos sobre la configuración más importante de las ráfagas de sol. + +Uso del **Genérico** puede establecer el botón **opacidad** en el movimiento del ratón y elija cómo mostrar los valores de la medida: absoluto, porcentaje o ambos. Estas dos características permiten la visualización de datos simplemente moviendo el mouse sobre el segmento: el segmento se resalta y los valores se muestran en el centro del anillo, mientras que la ruta del nodo raíz para el nodo seleccionado se muestra en la esquina inferior izquierda de la página. La configuración de Opacidad y Breadcrumb solo está disponible en Comunity Edition. La información sobre herramientas es un campo obligatorio, ya que muestra el valor del sector seleccionado. Por lo tanto, asegúrese de haberlo llenado antes de guardarlo utilizando el **Detalle de la explicación** tablero. En Comunity Edition tiene la opción de personalizar la ruta del nodo raíz, haciendo clic en el botón **Secuencia** y elija la posición, el tamaño de la cola de la etiqueta y el estilo del texto. **Secuencia** no está disponible en la edición Enterprise, está en desuso. La siguiente figura resume las tres características. + +.. figura:: media/image1070809.png + + Generic, Sequence and Explanation configuration + +En la siguiente figura se encuentra el estallido solar obtenido con datos de :numref:`exampleofdatsetsunburst`. + +.. figura:: media/image1101112.png + + From left to right: (a) Sunburst. (b) Sunburst category.(c) Sunburst subcategory. + +Adentro **Avanzado** puede establecer un valor para la escala que aumentará / disminuirá su gráfico. Debe establecer el valor numérico de la propiedad **escama**. + +Gráfico de Nubes de Palabras + +``` + +The wordcloud chart is a graphic to visualize text data. The dimension of the words and colors depend on a specified weight or on the frequency of each word. + +The dataset to create a wordcloud should have at least a column with attributes and only one column with numerical data which represents the weight to assign to each attribute. Choose one attribute as category field (the wordcloud accept only one attribute in the category box) and a measure as series field. + +Switch to the **Configuration** section to set the generic configuration of the chart and to custom fields of the **Word settings datails**. Here the use can decide if to resize the words accordingly to the measure retrieved in the dataset (**Series** option) or accordingly to the frequency of the attributes in the dataset (**Occurrences** option). Moreover it is possible to set the maximum number of words that you want to display, the padding between the words, the word layout and whether or not you want to prevent overlap of the words as showed in Figure below. + +.. figure:: media/image113.png + + Wordcloud chart specific configuration. + + +Treemap chart +~~~~~~~~~~~~~ + +The treemap is a graphical representation of hierarchical data, which are displayed as nestled rectangles. Each branch of the tree is given by a rectangle, which is tiled with smaller rectangles representing sub-branches. The area of the rectangles is proportional to a measure specified by a numerical attribute. The treemap is usefull to display a large amount of hierarchical data in a small space. + +To create a treemap chart you have to select a dataset as the one described for the sunburst chart in the Parallel chart. + +Once you have selected the dataset, choose the treemap chart type in the designer and then at least two attributes into the X-axis panel. The order of the attributes in the X-axis panel must reflects the order of the attributes in the hierarchy starting from the root to the top. + +Finally you can set generic configurations and colors palette in the **Configuration** tab and advanced configurations in **Advanced editor** tab. + +In Figure below we show the Treemap resulting with data of our example + +.. figure:: media/image11415.PNG + + From left to right: (a) Treemap. (b) Treemap sub-branches. + +Parallel chart +~~~~~~~~~~~~~~ + +The parallel chart is a way to visualize high-dimensional geometry and multivarious data. The axes of a multidimensional space are represented by parallel lines, usually equally spaced-out, and a point of the space is represented by a broken line with vertices on the parallel axes. The position of the vertex on an axis correspond to the coordinate of the point in that axis. + +To create a parallel chart select a dataset with at least one attribute and two columns with numerical values. You can find an interesting example of dataset in the next table where we display some of its rows. + +.. _exampleofdatsetparallel: +.. table:: Example of dataset for the parallel chart. + :widths: auto + + +--------+--------------+-------------+--------------+-------------+-----------------+ + | ID | sepal_length | sepal_width | petal_length | petal_width | class | + +========+==============+=============+==============+=============+=================+ + | 36 | 5.0 | 3.2 | 1.2 | 0.2 | Iris-setosa | + +--------+--------------+-------------+--------------+-------------+-----------------+ + | 37 | 5.5 | 3.5 | 1.3 | 0.2 | Iris-setosa | + +--------+--------------+-------------+--------------+-------------+-----------------+ + | 38 | 4.9 | 3.1 | 1.5 | 0.1 | Iris-setosa | + +--------+--------------+-------------+--------------+-------------+-----------------+ + | 39 | 4.4 | 3.0 | 1.3 | 0.2 | Iris-setosa | + +--------+--------------+-------------+--------------+-------------+-----------------+ + | 40 | 5.1 | 3.4 | 1.5 | 0.2 | Iris-setosa | + +--------+--------------+-------------+--------------+-------------+-----------------+ + | 41 | 5.0 | 3.5 | 1.3 | 0.3 | Iris-setosa | + +--------+--------------+-------------+--------------+-------------+-----------------+ + | 42 | 4.5 | 2.3 | 1.3 | 0.3 | Iris-setosa | + +--------+--------------+-------------+--------------+-------------+-----------------+ + | 43 | 4.4 | 3.2 | 1.3 | 0.2 | Iris-setosa | + +--------+--------------+-------------+--------------+-------------+-----------------+ + | 44 | 5.0 | 3.5 | 1.6 | 0.6 | Iris-setosa | + +--------+--------------+-------------+--------------+-------------+-----------------+ + | 45 | 5.1 | 3.8 | 1.9 | 0.4 | Iris-setosa | + +--------+--------------+-------------+--------------+-------------+-----------------+ + | 66 | 6.7 | 3.1 | 4.4 | 1.4 | Iris-versicolor | + +--------+--------------+-------------+--------------+-------------+-----------------+ + | 67 | 5.6 | 3.0 | 4.5 | 1.5 | Iris-versicolor | + +--------+--------------+-------------+--------------+-------------+-----------------+ + | 68 | 5.8 | 2.7 | 4.1 | 1.0 | Iris-versicolor | + +--------+--------------+-------------+--------------+-------------+-----------------+ + | 69 | 6.2 | 2.2 | 4.5 | 1.5 | Iris-versicolor | + +--------+--------------+-------------+--------------+-------------+-----------------+ + | 70 | 5.6 | 2.5 | 3.9 | 1.1 | Iris-versicolor | + +--------+--------------+-------------+--------------+-------------+-----------------+ + | 71 | 5.9 | 3.2 | 4.8 | 1.8 | Iris-versicolor | + +--------+--------------+-------------+--------------+-------------+-----------------+ + | 101 | 6.3 | 3.3 | 6.0 | 2.5 | Iris-virginica | + +--------+--------------+-------------+--------------+-------------+-----------------+ + | 102 | 5.8 | 2.7 | 5.1 | 1.9 | Iris-virginica | + +--------+--------------+-------------+--------------+-------------+-----------------+ + | 103 | 7.1 | 3.0 | 5.9 | 2.1 | Iris-virginica | + +--------+--------------+-------------+--------------+-------------+-----------------+ + | 104 | 6.3 | 2.9 | 5.6 | 1.8 | Iris-virginica | + +--------+--------------+-------------+--------------+-------------+-----------------+ + | 105 | 6.5 | 3.0 | 5.8 | 2.2 | Iris-virginica | + +--------+--------------+-------------+--------------+-------------+-----------------+ + | 106 | 7.6 | 3.0 | 6.6 | 2.1 | Iris-virginica | + +--------+--------------+-------------+--------------+-------------+-----------------+ + | 107 | 4.9 | 2.5 | 4.5 | 1.7 | Iris-virginica | + +--------+--------------+-------------+--------------+-------------+-----------------+ + | 108 | 7.3 | 2.9 | 6.3 | 1.8 | Iris-virginica | + +--------+--------------+-------------+--------------+-------------+-----------------+ + +In this example three different classes of iris are studied. Combining the values of some sepal and petal width or lenght, we are able to find out which class we are looking at. In Figure below (a part) you can find the parallel chart made with the suggested dataset. While in next figure (b part) it is easy to see, thanks to selection, that all iris with petal length between 2,5 and 5.2 cm and petal width 0,9 and 1,5 cm belong to the iris-versicolor class. + +.. _fromleftparallrighetchart: +.. figure:: media/image11617.png + + From left to right: (a) Parallel. (b) Parallel chart selection. + +Therefore, select **parallel** as chart type using the designer interface, then choose one or more attributes in the X-axis panel and one or more measures in the Y-axis panel. + +On the **Configuration** tab you can set the generic configuration for the chart and you must fill the **Series as filter column** filed under ”Limit configuration”. Under ”Tooltip configuration” there is new property available - **Maximum number of records to show tooltip**. It is used to limit showing tooltip in case there are lot of records returned from dataset, which make chart more readable. + +Heatmap chart +~~~~~~~~~~~~~ + +Heatmap chart uses a chromatic Cartesian coordinate system to represent a measure trend. Each point of the Cartesian system is identified by a couple of attributes. Note that one attribute must be a datetime one. Meanwhile, each couple corresponds to a measure that serves to highlight the spot with a certain color according to the chosen gradient. Figure below gives an example of how an heatmap chart looks like inside Knowage. + +.. figure:: media/image118.png + + Heatmap example. + +Before configuring a heatmap chart, be sure that your dataset returns at least two attributes, one of which **must** be a datetime one, and (at least) one measure. Once entered the chart designer, choose the “Heatmap” type and move to the “Structure” tab. Use the datetime attribute and an other attribute as category fields and one measure as series fields. Figure below shows an example. + +.. figure:: media/image119.png + + Configuring the attributes and the series for the heatmap chart. + +Note that for series axis it is possible to specify the values’ range by assigning a minimun and the maximum value, as shown in figure below. Otherwise, the engine will automatically link the axis scale to dataset results set. + +.. figure:: media/image12021.png + + Configure min and max values for series. + +The next step is to move to **Configuration** tab and select the **Color palette** icon. Here (figure below) the user has to define the chromatic scale which will be associated to the measure values. The panel will demand the user to insert the first, the last color and the number of bands that will constitute the color scale. + +.. _addgradientpanel: +.. figure:: media/image122.png + + Add gradient panel. + +The engine will create a progressive color scale as shown in the left image of figure below. To custom the scale the user can use the Preset colors and use the arrow to move up and down Heatmap chart the added color or the user can increase the number of steps and then +some intermediate color to leave more contrast between them. + +.. figure:: media/image12324.PNG + + Custom color scale. + +Remember to edit both **Legend** and **Tooltip** configuration in the **Tooltip details** panel to improve the readability of the chart. + +Chord chart +~~~~~~~~~~~ + +Chord diagram is a graph which allows to show relationship between entities and between data in a matrix. The entities can belong to an unique category while the arc be non-oriented or belong to two different categories. In this latter case, they have direct arcs. The data are arranged radially with arcs that represent the connection between points. The width of the arc connecting two points depends on the weight assigned to the edge connecting these two points. This graphic is usefull when you want to represent a large number of data in a small space. + +The chord diagram requires a dataset that have a column with numerical values. These represent the weight of the arc connecting two points. It also must have two columns with the entries for the entities to be connected in the diagram. These two columns must have the same set of values so that the engine can understand the relation between all the entities. If there is not a relation between two entities the weight of the arc is zero. Note that when you create a directed chord diagram with two different categories, all the relations between entities of the same category have a zero weight. + +An example of dataset for the chord chart is represented in Table below: + +.. table:: Example of dataset for the chord chart. + :widths: auto + + +--------------------+--------------+-----------+ + | CUSTOMER\_ CITY | STORE\_ CITY | VALUE | + +====================+==============+===========+ + | Beaverton | Portland | 4609.0000 | + +--------------------+--------------+-----------+ + | Lake Oswego | Portland | 4201.0000 | + +--------------------+--------------+-----------+ + | Milwaukie | Portland | 5736.0000 | + +--------------------+--------------+-----------+ + | Oregon City | Portland | 3052.0000 | + +--------------------+--------------+-----------+ + | Portland | Portland | 3984.0000 | + +--------------------+--------------+-----------+ + | W. Linn | Portland | 3684.0000 | + +--------------------+--------------+-----------+ + | Albany | Salem | 5544.0000 | + +--------------------+--------------+-----------+ + | Corvallis | Salem | 8542.0000 | + +--------------------+--------------+-----------+ + | Lebanon | Salem | 8015.0000 | + +--------------------+--------------+-----------+ + | Salem | Salem | 6910.0000 | + +--------------------+--------------+-----------+ + | Woodburn | Salem | 6335.0000 | + +--------------------+--------------+-----------+ + | Albany | Albany | 0.0000 | + +--------------------+--------------+-----------+ + | Beaverton | Beaverton | 0.0000 | + +--------------------+--------------+-----------+ + | Corvallis | Corvallis | 0.0000 | + +--------------------+--------------+-----------+ + | Lake Oswego | Lake Oswego | 0.0000 | + +--------------------+--------------+-----------+ + | Lebanon | Lebanon | 0.0000 | + +--------------------+--------------+-----------+ + | Milwaukie | Milwaukie | 0.0000 | + +--------------------+--------------+-----------+ + | Oregon City | Oregon City | 0.0000 | + +--------------------+--------------+-----------+ + | Portland | Portland | 0.0000 | + +--------------------+--------------+-----------+ + | Salem | Salem | 0.0000 | + +--------------------+--------------+-----------+ + | W. Linn | W. Linn | 0.0000 | + +--------------------+--------------+-----------+ + +Once you have selected the dataset open the designer and select chord chart type. Then choose the two entities in the X-axis panel and the value in the Y-axis panel as showed in figure below. Now you are ready to customize the chart setting the generic configuration and the palette on **Configuration**. + +.. figure:: media/image12526.png + + Chord configuration. + +Gauge chart +~~~~~~~~~~~ + +Gauge chart uses needles to show information as a dial reading. It allows to visualize data in a way that resembles a real-life speedometer needle. The value of the needle is read on a colored data scale. Colors are used to provide additional performance context (typically green for good and red for bad). This chart type usually is used in dashboards to show key performance indicators or any measure having reference values. + +For gauge chart you should have only series items, the one that gives you values for the chart. So, the defined dataset to be used should provide numerical data for the Y-axis for the gauge chart. After selecting the dataset go to the designer and select **gauge** in chart type combobox. Then choose one or more measure on the Y-axis panel on the **Structure**. Moreover you must not forget to provide all data needed for the **Axis style configuration** of the Y-axis. + +When you finished to set all the mandatory and optional parameters and configurations in the **Structure** tab you can select the **Configuration** tab and set the generic configuration of the chart. + +Bubble chart +~~~~~~~~~~~~ + +A bubble chart requires three dimensions of data; the x-value and y-value to position the bubble along the value axes and a third value for its volume, z-value. It is a generalization of the scatter plot, replacing the dots with bubbles. + +.. figure:: media/bubble_chart.png + + Bubble chart. + + +Inside X,Y,Z containers, user can put only **measure values**. Inside Categories container user can put **attributes** that he wants to see in the **tooltip**. + +.. figure:: media/bubble_chart_conf.png + + Bubble configuration. + + +.. figure:: media/bubble_tooltip.png + + Bubble tooltip. + + +Inside **Advanced tab**, user can find configuration for **plotband** and **plotline** of xaxis and yaxis. + +.. figure:: media/bubble_plotband_and_line.png + + Bubble plotband and plotline configuration. + + +User also has option for **splitting serie** by one of two categories. Split option has limit on **maximum** two categories. User can set which category will be used for coloring bubbles. And also can show/hide values that are inside bubbles. + +.. figure:: media/bubble_split_conf.png + + Bubble split configuration. + + +.. figure:: media/bubble_split.png + + Bubble split examples. + +Difference between **One category - split disabled** and **Two categories - split disabled** is what is present in the tooltip. + + +A short comment on chart drill down +--------------------------------------- + +Knowage **Chart Engine** allows you to drill down into categories. This means that the user can explore the details of each category as many times as configured. Indeed, to let the chart admits the drill down, it is necessary first that the chart in place allows it. Secondly the user must have dragged and dropped multiple attributes into the category axis in the **Configuration** tab. The order of the attributes in the X-axis panel determines the sequence in which the categories are going to be showed. When executing the chart the label of the category is linkable and it is possible to click on the label to drill down. + +The chart that enables the drill down are: + +- Bar Chart +- Line Chart +- Pie Chart +- Treemap + +To give an idea of the outcome, we take as instance the Bar Chart drill down. In the following example, the selected categories are four and called: ``product_family``, ``product_department``, ``product_category`` and ``product_subcategory``. Once we open the document, we get as shown below: + +.. figure:: media/image127.png + + Drillable Bar Chart + +When selecting ``shelf_depth`` measure of the Food category one gets (see next figure): + +.. figure:: media/image128.png + + Drillable Bar Chart: first drill + +Once again, we can select ``Frozen food`` subcategory and drill to a second sub-level as below: + +.. figure:: media/image129.png + + Drillable Bar Chart: second drill + +And so on to the fourth subcategory. Selecting the “Back to: ...” icon available at the right corner of the graphic, the user can get back to the previous level. This efficient feature allows the user to have a deep insight of the analysis and draw important conclusions from it. + +Stand alone charts +------------------------ + + .. warning:: + **This functionality is deprecated** + + Design of stand alone charts is **deprecated** and may be removed in future releases, therefore we invite users to exploit the cockpit designer for charts instead. + + +The previous chapters were dedicated to the end user approaching the Knowage Chart engine. We stressed how the final user must pass through the Cockpit interface to develop graphs. We want now spend some words about the developer experience. Indeed, if you are a technical user you can also create a chart as a stand alone document. + +Once you enter the Knowage environment with developer credentials, open the technical menu directly into the **Documents Development** area, as shown in Figure below. + +.. figure:: media/image130.png + + Documents Development. + +Then click on the “Plus” icon of the **Create Document** feature and select **Generic Document**. + +.. figure:: media/image131.png + + Create a new document. + +You will be asked to fill in the form. We give an example in the following figure. + +.. _documentdetailschart: +.. figure:: media/image132.png + + Document Details. + +The fields marked with an asterisk are mandatory. Select the Chart type and engine. Choose the dataset with which you want to manage your analysis. Use the magnifier to choose among the available datasets. Remember to pick out in which folder you want your chart to be stored (see next figure) and finally save. + +.. _selectfolderforchart: +.. figure:: media/image133.png + + Select the folder in which you want your chart to be saved. + +A new template can be generated through the editor clicking on **Template build** as showed below or a template previously created can be uploaded. + +.. figure:: media/image134.png + + Template build. + +If you choose to implement the new Chart through the Template Build feature, the steps to follow are exactly the same of those seen for the final user. In fact, once you click on the Template Build icon, you are redirected to the Chart designer. In this case, by the way, another functionality is enabled, the Cross Navigation. + + +Cross Navigation +---------------------- + +When you develop a standalone chart it is possible to add a cross navigation path to it. This means that, once the chart is launched, its elements becomes clickable and it redirects the user to a second document. + +For charts documents outputs parameters are automatically generated during the creation of the document. Therefore you can define cross +navigation in the default way, as explained in Cross Navigation. +``` diff --git a/functionalities-guide/cockpit/index.es.rst b/functionalities-guide/cockpit/index.es.rst new file mode 100644 index 00000000..aab1c670 --- /dev/null +++ b/functionalities-guide/cockpit/index.es.rst @@ -0,0 +1,1879 @@ +# Cabina + +Knowage permite a los usuarios finales *cabinas interactivas autoconstruidas* a través de una interfaz intuitiva e interactiva, con unos pocos clics y un simple arrastrar y soltar. Esto le permite componer sus documentos analíticos con múltiples widgets y definir asociaciones entre ellos, de modo que al hacer clic en un widget, los datos se actualizan automáticamente en otros widgets. + +.. figura:: media/image135.png + + Cockpit document example. + +Permite *mash-up de datos* para integrar datos empresariales y datos de origen externo. + +Los documentos de cabina pueden ser creados y ejecutados tanto por usuarios técnicos como por usuarios finales y forman parte del sistema de informes ad-hoc de Knowage. Un aspecto clave es que diferentes widgets pueden basarse en diferentes conjuntos de datos y, por lo tanto, en diferentes fuentes de datos. El único requisito necesario para definir asociaciones entre dos o más conjuntos de datos es la presencia en cada uno de ellos de una o más columnas que contengan los mismos datos. + +.. advertencia:: +**Excepción de estructura de sección** + + Since there are no differences between the cockpit interface reached by a final user and the one reached by a technical user, the cockpit designer is described in one unique My first Cockpit for both those kind of users. By the way, when necessary we will highlight how the same functionality can be exploited accordingly to the user’s role. + +## Mi primera cabina + +Puedes crear tu nuevo Cockpit desde el **Análisis** zona de la **Área de trabajo** haciendo clic en el icono "Más" y seleccionando **Cabinas** si ingresa a Knowage Server como usuario final, mientras que puede ingresar al navegador de documentos e iniciar una nueva cabina usando el ícono "Plus" si ingresa a Knowage Server como administrador. + +.. importante:: +**Llegar al diseñador de la cabina** + + We stress that the cockpit interface is reached by the final user and the administrator following two different paths. + +Veamos cómo construir una cabina y cómo se muestra la interfaz dentro del servidor. Una vez abierta, la interfaz de la cabina es una página vacía con una barra de herramientas que contiene diferentes opciones descritas en la tabla a continuación. + +.. tabla:: Barra de herramientas del editor de cabina. +:widths: automático + +\+--------------------------------+-----------------------+-----------------------+ +| | de iconos Nombre | | de funciones +\+================================+=======================+=======================+ +| .. figura:: media/image136.png | **Menú de cabina** | Menú de configuración de | +| | | Cabina. | +\+--------------------------------+-----------------------+-----------------------+ +| .. figura:: media/image137.png | **Añadir widget** | Abre una ventana | +| | | donde puede crear | +| | | un nuevo gráfico o tabla, | +| | | añadir textos, imágenes o | +| | | Documentos de conocimiento. | +\+--------------------------------+-----------------------+-----------------------+ +| .. figura:: media/image138.png | **| general Abre la ventana | +| | configuración** | donde se establece el | +| | | | general de la cabina +| | | opciones (nombre, etiqueta, | +| | | mostrar menú, etc.) y | +| | | estilo de widget (encabezado, | +| | | títulos, fronteras | +| | | etc.). | +\+--------------------------------+-----------------------+-----------------------+ +| .. figura:: media/image139.png | **| de datos Abre una ventana | +| | configuración** | donde puede administrar | +| | | el conjunto de datos, el | +| | | asociación entre | +| | | conjuntos de datos y la | +| | | frecuencia de actualización. | +\+--------------------------------+-----------------------+-----------------------+ +| .. figura:: media/image140.png | **Selecciones** | Agrega un widget que | +| | | gestiona las selecciones. | +\+--------------------------------+-----------------------+-----------------------+ +| .. figura:: media/image141.png | **Borrar caché** | Limpia | temporales +| | | datos. | +\+--------------------------------+-----------------------+-----------------------+ +| .. figura:: media/image142.png | **Guardar como** | Abre la ventana | +| | | Para guardar la | de la cabina +| | | documento como un nuevo | +| | | documento. | +\+--------------------------------+-----------------------+-----------------------+ + +Haciendo clic en el botón **Agregar widget** Puede agregar un widget que contenga un **Mensaje de texto**un **Imagen**un **Gráfico**un **Mesa**un **Tabla cruzada**un **Documento**el **Selecciones activas** o el **Selector** a su cabina, como se muestra a continuación. + +.. figura:: medios/image143\_bis.png + + Widget Type. + +A continuación entramos en detalles de cada widget disponible. + +Widget de texto + +``` + +By clicking the button Text Widget you can add text to your cockpit. As shown in figure below, the widget editor opens and it is divided in three tabs: the **Text editor**, +the **Style**, the **Dataset** and the **Filters** tab. + +.. _texteditwidgetconf: +.. figure:: media/image144.png + + Text editor of text widget configuration. + +On the “Text editor” tab you can type the desired text in center panel and customize it. Using the dataset tab it is possible to associate dataset values to the text and +read it real time at each execution. Move to the dataset tab to add a dataset to the widget. Then, going back to the Text editor tab, the user will find the dataset +columns on the right side, as well as a set of functions to eventually apply to the fields. We summed up main steps in the Figure below. To add a function to a measure +first select the desired function and then the field of numeric type. + +.. figure:: media/image1454647.png + + Editing a dynamic text. + +It's also possible to add variables values if at least one of them is defined. During the execution of the widget the value will be displayed based on the current variable value. + +.. figure:: media/image144b.png + + Variables in text widget. + +On the “Style” tab you can customize the text widget. We have provided all details about this tab in the Table widget. On the “Dataset” tab you can add more dataset to be +used in the dynamic value. Finally, the “Filters” tab can be used to extract limited output from the dataset. We put details off to the table widget subsection. + +Image widget +``` + +Haciendo clic en el botón **Widget de imagen** puede agregar imágenes a su cabina. Como ya se ha visto el editor de widgets se abre y se divide en +tres secciones. + +En el **Galería** puede cargar una imagen, eliminarla o seleccionar una de la galería. Consulte la siguiente figura. + +.. figura:: media/image148.png + + Gallery tab of Image Widget Configuration. + +En el **Estilo** puede configurar el estilo de su widget de imagen con las diferentes opciones que ofrece esta pestaña. Muchos de ellos están definidos en el widget de tabla que encontrarás más adelante. + +En el **Cruz** puede definir la navegación a otro documento, como se muestra en la figura siguiente. + +.. figura:: media/image149.png + + Cross tab of Image Widget Configuration. + +.. advertencia:: +**Navegación cruzada solo para usuarios técnicos** + + Due to the fact that parameters can only be managed by a technical user the cross navigation cannot be implemented by the final user. + +Para ello, debe activar **Habilitar la navegación cruzada** y seleccione el documento de destino a través de la lista de definición de navegación cruzada. +Esta última bandera es opcional. Si selecciona una definición de navegación cruzada, cuando inicie la navegación cruzada irá directamente al documento de llegada. +Si la definición de navegación cruzada no está definida, cuando inicie el widget de imagen, se mostrará una ventana emergente (consulte la figura a continuación) con la lista de definiciones de navegación cruzada que existen para esta cabina. + +.. \_crossnavmultchoice: +.. figura:: media/image150.png + + Cross navigation multiple choices. + +Widget de gráfico + +``` + +Charts are an essential representation of data, Knowage let you use many different charts type and configure them according to your needs. We have provided all details about charts type and configuration in Chart chapter. + +We recall that also for chart widget it is possible to set cross navigation on elements. + +.. warning:: + **Cross navigation only for technical users** + + Due to the fact that parameters can only be managed by technical user the cross navigation cannot be implemented by the final user. + +As shown in next figure, it is mandatory to enable the cross navigation feature by using the dedicate tab of chart editor GUI. It is mandatory to choose the column element to be passed to the destination document and associate it to the right output parameter (previoulsy added to the document using the detail interface). + +The cross navigation name can be left empty. In case multiple cross navigation definitions have been configured for the document, a pop up will be displayed, letting the user to choose which destination to reach (exactly as we saw earlier for Image widget in the last figure of that paragraph). + +.. _crossnavchartwidget: +.. figure:: media/image151.png + + Cross navigation for chart widget. + +In addition, if the navigation expects other parameters to be passed, use the bottom part of the page to add the additional parameters. Figurebelow shows an example. + +.. figure:: media/image152.png + + Add all output parameters involved in the cross navigation. + +It is also possible using Solr datasets and calculated fields with charts. + +Dataset fields editing and configuration is possible using the first tab inside widget edit mode, in this way, for example, users can modify aggregations for measures: + +.. figure:: media/image152b.png + +In this way it is possible adding new calculated fields on chart by clicking on "Add Calculated field", the standard calculated field editing mode will appear. + +.. figure:: media/image152c.png + +Adding new calculated fields is easy as using other measure fields, using Chart Engine Designer structure tab: + +.. figure:: media/image152d.png + + +Table widget +``` + +El **Configuración de la tabla de widgets** se abre y le guía a través de los pasos para configurar el widget. Se abre la ventana emergente que muestra el **columna** , como puede ver en la figura a continuación. En detalle, es obligatorio seleccionar un conjunto de datos mediante el cuadro combinado (solo si se ha cargado al menos un conjunto de datos mediante el **Configuración de datos** feature) o haciendo clic en el icono |image156| disponible justo al lado de la línea combobox. Puede paginar la tabla especificando el número de filas por hoja. En consecuencia, el usuario puede establecer propiedades de columnas. + +.. |imagen156| imagen:: media/image153.png +:ancho: 20 + +.. figura:: media/image154.png + + Table configuration window. + +De hecho, el área de la columna se divide en dos partes: en la parte superior están los botones para agregar una nueva columna o un campo calcutado. También la nueva funcionalidad de agrupación de columnas está disponible aquí. En la sección inferior, tan pronto como se seleccione el conjunto de datos, puede indicar la columna de ordenación o la columna de selección modal. La selección modal sirve para especificar qué valor se pasará a otros widgets (si la interacción está habilitada) al hacer clic en la celda en el momento de la ejecución del documento. Puede especificar este campo seleccionando un valor del cuadro combinado. De la misma manera, se indica la columna de ordenación y el tipo de orden que dirige el orden de las filas. Puede seleccionar el campo y el pedido de los cuadros combinados dedicados. + +Cuando se agrega un conjunto de datos a un widget de tabla, todas sus columnas se enumeran a continuación. Si el usuario no desea mostrar algunos de ellos, puede usar el botón de eliminación disponible al final de cada fila de columna, como se muestra a continuación. + +.. figura:: media/image155.png + + Delete a column. + +En caso de cancelación accidental o nuevos requisitos de tabla, es posible volver a agregar columnas. Para añadir una nueva columna hay que +haga clic en el botón **Agregar columna** en la parte superior derecha del segundo cuadro. Una vez abierto, puede seleccionar una o más columnas. Cuando haya terminado de seleccionar las columnas deseadas, puede hacer clic en el botón Guardar y sus nuevas columnas aparecerán en la lista de campos. Consulte la figura a continuación. + +.. figura:: media/image156.png + + Add a new column. + +**Administrar grupos de columnas** abrirá un menú para agregar o quitar grupos de columnas y establecer su estilo. Un grupo de columnas es un contenedor para más de una columna que mostrará un encabezado común entre ellas. + +.. figura:: media/image156b.png + + Example column group. + +Asimismo, para añadir un campo calculado hay que pulsar en el botón **Agregar campo calculado** junto al icono de agregar columna. Una vez abierto el Asistente de campo calculado, debe escribir un alias para su campo calculado en el área dedicada en la esquina superior del asistente. +Luego puede elegir de la lista sinebar izquierda los campos que desea usar en su fórmula. También puede utilizar funciones aritméticas o utilizar las funciones disponibles en el menú (**Agregaciones**, **totales de columnas**, **Variables**). +Si lo prefiere, puede crear o modificar la expresión manualmente directamente en el panel editable. +Cuando esté satisfecho con su expresión, puede hacer clic en validar para verificar su fórmula sintax o el botón Guardar y su campo calculado aparecerá en la lista de campos. +Proporcionamos un ejemplo en la siguiente figura. + +.. figura:: media/image157.png + + Add a calculated field. + +Puede elegir entre el comportamiento a nivel de conjunto de datos o el nivel de tabla (predeterminado), es decir, la modalidad de cálculo que implicará campos de tabla o columnas de conjunto de datos para obtener el resultado. +Si elige el comportamiento a nivel de conjunto de datos, el resultado del cálculo se realizará solo a nivel de columnas de conjunto de datos y la agregación implicará todo el resultado del cálculo. + +.. figura:: media/image157b.png + + Dataset-level behaviour + +Si Dataset es del tipo Solr, las columnas que se muestran en el panel derecho son campos de columnas de dataset y la elaboración de la fórmula de campo calculada se calcula sobre la marcha. + +.. figura:: media/image158b.png + +Si se establecen variables para la cabina actual, aparecerá el botón de menú de variables, lo que permite agregar valores de variables en la expresión de campo calculada. + +.. figura:: media/image157c.png + +Menú Variables + +En la sección inferior de la ventana, puede ver los campos de la tabla (con su tipo de agregación) enumerados y también puede ordenar las columnas que se muestran en la tabla arrastrando +arriba o abajo, inserte un alias de columna y personalícelo agregando configuraciones de fuente y estilo utilizando el icono en forma de pincel, como puede ver en la figura a continuación. +Aquí puede encontrar características de configuración para ajustar el tamaño de la columna, los caracteres máximos de celda, ocultar las opciones de encabezado de columna o columna y el interruptor de expansión de filas. + +.. figura:: media/image157d.png + +Configuración de columnas + +Si oculta la columna (desde esta vista o desde la lista de columnas), la columna no será visible, pero seguirá utilizándose con fines de agregación. +Si habilita el **función de intervalo de filas**, todos los mismos valores visibles de la columna se contraerán en uno, para evitar repeticiones. + +Si la columna es una medida, habrá más funcionalidades disponibles: + + - Inline chart mode: you can choose the visualization type of the measure, and if you choose chart and maximum/minimum values, a chart will appear in the view to represent the cell measure. + - Thresholds: you can choose to set some thresholds that will trigger font color, background color or will show icons if the chosen condition is satisfied. + - Format: you can choose the prefix, suffix and the precision (i.e. 9.8 m/s). Please be aware that the data will be formatted following the locale of the user. Otherwise you can choose to treat it as string. + +.. \_columnsettings: +.. figura:: media/image158.png + + Column settings. + +Tenga en cuenta que aquí puede indicar el tipo de columna y la agregación. Para agregar una agregación a una columna, debe controlar el tipo de datos que tiene esa columna. Sólo se puede agregar una agregación si el valor de la columna es del tipo "número". Las diferentes funciones de agregación son: *ninguno (tampoco puede agregar ninguna función de agregación)*, *Suma*, *Promedio*, *Máximo*, *Mínimo*, *Contar* y *Cuenta distinta*. + +Si se ha establecido un grupo de columnas, otra opción estará disponible para establecer el grupo opcional que pertenece a la columna. + +Para todas las columnas, si se establece al menos una variable, aparecerá el cuadro de configuración de variables. Dependiendo del uso de la variable, será posible establecer un encabezado dinámico u ocultar la columna condicionalmente. + +.. figura:: media/image158c.png + + Variable settings box. + +Al hacer clic en el botón más, puede agregar una o más condiciones. Las posibles acciones son: + + - Hide column: the column will be shown conditionally depending on the condition set. + - Set column header name: the column name will be replaced by the variable value. + +Se pueden establecer varias condiciones, pero una condición que cumpla con el "=" tendrá mayor prioridad. + +.. figura:: media/image158d.png + + Variable action set. + +El **Estilo** es donde se puede personalizar la tabla utilizando las diferentes opciones de estilo. Se divide en ocho partes: + +* En **Resumen** puede mostrar el total de la columna y personalizarla escribiendo el nombre del resumen y utilizando configuraciones de fuente y estilo. Consulte la figura a continuación. + +.. figura:: media/image159.png + + Summary section of the Style tab. + +* En **Filas** sección se pueden configurar las filas de la tabla para que se adapten de forma automática o seleccionar una altura fija. También puede mostrar el total de filas. Mientras que la opción multiseleccionable le permite seleccionar múltiples valores y pasarlos a otros widgets de cabina u otros documentos externos. Consulte la figura a continuación. + +.. figura:: media/image160.png + + Rows section of the Style tab. + +* En **Rejilla** puede agregar bordes a la tabla y agregar color a filas alternativas. En esta sección puedes encontrar diferentes opciones para personalizarlas. Consulte la figura a continuación. + +.. figura:: media/image161.png + + Grid section of the Style tab. + +* En **Estilo de encabezado** encontrará las diferentes opciones de estilo para el encabezado de la tabla. Consulte la figura a continuación. + +.. figura:: media/image162.png + + Header style section of the Style tab. + +* En **Títulos** puede agregar los títulos al widget y modificar el tamaño y el peso de la fuente. En esta sección también puede cambiar la altura del título del widget. Consulte la figura a continuación. + +.. figura:: media/image163.png + + Titles section of the Style tab. + +* En **Fronteras** puede agregar un borde al widget y personalizarlo utilizando los colores, el grosor y el estilo. Consulte la siguiente figura. + +.. figura:: media/image164.png + + Borders section of the Style tab. + +* En **Otras opciones** Puede agregar las sombras en el widget, puede establecer el color de fondo del widget y es posible deshabilitar o habilitar la opción de captura de pantalla para ese widget en particular. Consulte la siguiente figura. + +.. figura:: media/image165.png + + Other Options section of the Style tab. + +Una vez que se haya implementado la configuración del estilo de tabla, puede cambiar a la siguiente pestaña. La pestaña "Cruz" es donde se define la navegación a otros documentos. Es visible para los usuarios finales, pero solo es configurable por un usuario técnico (como un administrador). + +Finalmente, la pestaña "Filtros" es donde puede filtrar los resultados de la tabla agregando un límite a las filas o una condición en las columnas. en la siguiente ilustración se muestra un ejemplo de cómo establecer las filas límite o las condiciones en las columnas del conjunto de datos. + +.. \_filterstabwidgetconf: +.. figura:: media/image168.png + + Filters tab of the table widget configuration. + +Una vez que haya terminado de configurar las diferentes opciones de configuración del widget de tabla, simplemente haga clic en "Guardar" y su nuevo widget es +se muestra dentro de la cabina. + +Widget de tabla cruzada + +``` + +Similar configurations are available also for the Cross Table widget. In this data visualization option, you still have the tabs: **Dataset** tab, **Configuration** tab, the **Style** tab and the **Filters** tab as you can see below. + +.. figure:: media/image169.png + + Dataset section of the crosstab widget configuration. + +Using the “Dataset” tab the user can add the dataset to take values from. Consequently, it is necessary to select the fields you wish to appear as columns, those as row and measures to be exhibited in the pivot table. See figure below. Remember to set column and row fields as attributes, while measure fields as numbers. + +.. figure:: media/image170.png + + Selecting columns, rows and measures of the crosstab. + +There is also the possibility to add calculated fields as measures clicking on the "Add calculated field button". +The calculated field will work exactly as in the table widget. After creating a calculated field there will be the possibility to edit, remove it or set the properties for it's column clicking on the new measure buttons. + +.. figure:: media/image170b.png + + Calculated field detail. + +Once the columns, rows and measures have been selected the style of each column can be set by clicking on the cog settings icon. A popup will open with different options for the selected columnn. See figure below. + +.. figure:: media/image210.png + + Column style popup. + +It is possible to sort the crosstab according to the values of the selected column or, alternatively, according to columns not visible in the crosstab. It can also be set the style of the column, such as the font size, the font weight or the cell alignment. There is also the possibility to specify the size of the column in pixels (you can also use percent values but it is better to use pixels). + +In case the selected column is of type measure, there is a dialog to configure the behaviour of that field: + +.. figure:: media/image490.png + + Measure configuration dialog. + +A particular option for a measure is **Exclude from Total and SubTotal**: that checkbox excludes the measure from the sums of Total and SubTotal fields makin the relatives table cells empty. + +.. figure:: media/image211.png + + Measure threshold setting. + +As figure above shows, you can also manage threshold. For measures only, it is possible to associate a particular icon or a specific background color to a particular measure's value or range. +To do so add a new threshold, set a condition for it to appear, and choose the icon from the list or select the color that will be changed to the cell. +It is possible to add more or to remove thresholds using the add or delete button. + +.. figure:: media/image211c.png + + Variables header value. + +If one or more variables are set, in column and measure settings another field will appear. It is possible to set the header name to be dynamic using one of the variables set. +If one of the variables are selected in the combo as in example, the header name will be changed depending on the current variable value. + +.. figure:: media/image211b.png + + Column style. + +It's also possible to set style elements for both attributes and measures. In measures will also be possible to set the precision and prefix/suffix of the cell value. +The comma and dot used for decimals and thousands will be automatically changed depending on user's locale. + +Once the dataset has been properly configured, you can proceed to the “Configuration” tab. + +The latter is made up of three sections: **General**, **On rows** and **On columns**, as Figure below shows. + +.. figure:: media/image171.png + + Configuration tab interface. + +In the “General” section you can set the following features: + +- define the maximum cell number to show; +- decide to hook measures to columns or rows; +- decide to show percentages of measures related to columns or rows. + +Thanks to the “On rows” feature, you can easily compute totals or subtotals on rows. Figure below exhibit an example. + +.. figure:: media/image172.png + + Computing totals and/or subtotals on rows. + +Otherwise, thanks to the “On columns” feature, you can easily compute totals or subtotals on columns. Figure below exhibit an example. + +.. figure:: media/image173.png + + Computing totals and/or subtotals on columns. + +Selecting the "Hide rows on just null values" will hide all the rows with just 0 or null values, avoiding space waste if unneeded. + +The "Fix attribute's columns" will pin to the left the columns containing the attributes, so side scrolling will be available without losing those columns. + +.. figure:: media/image173b.png + + Pinned columns example. + +The "expand/collapse" functionality will add a + and - button in your rows, in order to easily aggregate your data. +In the widget menu you will also find the expandall/collapse all buttons, in order to reset closing or opening your whole widget. + +Be aware that to use this functionality columns subtotal should be selected. If not the functionality check will enable it automatically. + +.. figure:: media/image173c.png + + Expand/collapse example. + +Switching to the “Style” tab you can find the general style settings available for the crosstab. + +- **Crosstab General Options** where the rows' height, the general font and font size can be set; in particular, the layout combo determines how the columns resize themselves in respect of the contained value; + +.. figure:: media/image174.png + + General style options for crosstab. + +- **Crosstab Headers Font Options** where you can configure the header style settings as color, background, font, etc. + +.. figure:: media/image175.png + + Crosstab Headers Font Options for crosstab. + +- **Measures Font Options** where you can configure several style options for measures, such as color, background, font size, etc. + +.. figure:: media/image176.png + + Measures Font Options for crosstab. + +- Using the **Grid** section you can mark (or not) grid borders, decide for border style, thickness and color. You can also alternate row indicating different colors. + +.. figure:: media/image177.png + + Grid Options for crosstab. + +- In the **Measures Headers** section you can configure different style option for measure headers, such as color, background, font size, etc. + +.. figure:: media/image178.png + + Measures Headers Option for crosstab. + +- In the **Total** section you can set color and background of totals (if any). + +.. figure:: media/image179.png + + Color settings for Totals. + +- In the **Subtotal** section you can set color and background of subtotals (if any). + +.. figure:: media/image180.png + + Color settings for Subtotals. + +- In the **Titles** section you can add titles to widget and customize them using different styles. + +.. figure:: media/image181.png + + Title settings. + +- In the **Borders** section you can add borders to widgets and customize them using different styles. + +.. figure:: media/image182.png + + Border settings. + +- In the **Other Options** section you can add a shadow to widget layout and indicate its measure, color the widget background at convenience and it is possible to disable or enable the screenshot option for that particular widget. + +.. figure:: media/image183.png + + Other Options for crosstab. + +Once some or all (at least the mandatory) of the above mentioned setting features have been set you can save and the widget will be inserted into the cockpit area. + +.. figure:: media/image498.png + + Cross navigation for cross table widget. + +In addition to other cross-navigations, for cross table widget it is possible to set as a dynamic value the name of the selected measure column or the selected category. The choice is available from the combobox. + + +Document section +~~~~~~~~~~~~~~~~ + +The Document widget allows to add an external document into the cockpit area. This widget supports documents like reports, graphs, maps, etc. + +Use the Data configuration button to add a document source to the cockpit. Click on the “Plus” icon on the right half of the page to choose among all available documents. + +The Document Widget configuration is divided into two parts: **Custom** tab and **Style** tab as you can see from Figure below. + +.. figure:: media/image185.png + + Custom tab of the Document widget. + +The Custom tab is the place where the document is uploaded while the Style tab is where all style options are set. + +Selection widget +~~~~~~~~~~~~~~~~ + +This widget is related to the association concept so in this subsection we give information on how to add and custom the **Selection Widget** into the cockpit area and its functioning, while we refer to the dedicated Document section for details on how to set (global) associations. + +To enable the Selection widget, which means the possibility to have all associations listed and accessible on a widget, the user must open the “Selection” feature through the “Add widget” functionality and configure the demanded options. Figure below shows the “Selection widget configuration” interface. + +.. figure:: media/image186.png + + Selection widget configuration. + +The Selection Widget will display the elements selected by the user. Figure below shows an example. + +.. figure:: media/image187.png + + Selection widget outlook. + +If global associations have been set, clicking on table, cross table or chart elements will update all corresponding widgets. Otherwise, only the widget on which selection has been made Selector Widget will be updated. In both cases the Selection widget will display the +highlighted attribute values. + +Selector Widget +~~~~~~~~~~~~~~~ + +The **Selector Widget** is useful when an end user (a user with a USER tole type) wants to add a parameter to the document. + +.. note:: + **Selector widget** + + A technical user can use the association with an Analytical Driver to filter on cockpit. + +.. figure:: media/image188.png + + Selector widget outlook. + +In detail, use the **Columns** tab to select the dataset and the dataset column on which you want to apply the filter. Then custom the **Select modality** options; for instance, choose between single or multivalue or to use a list or a combobox. Note that for the list option you can further choose among “vertical”, “horizontal” or “grid”. You can also decide to add a default value, chosen from main column’s first item, main column’s last item or to simply assign a static value. Finally, by clicking on the Wrap Text option it is possible to wrap the text shown in the selector; this option is useful when the categories to choose from are sting of long dimensions. + +In the case of the selector of type list "grid" it is also possible to set the grid columns width. + +.. figure:: media/image304.png + + Grid columns width. + +Move to the **Style** tab to set the widget style in terms of: label, titles, borders, shadows and background color. Figure below shows a customization example. + +.. figure:: media/image189.png + + Selector widget configuration. + +Finally use the **Filters** tab to handle pagination or filter on a dataset column. + +.. figure:: media/image190.png + + Selector filters. + +The Selector widget works effectively as a ready-to-use filter panel. + +.. figure:: media/image191.png + + Selector widget execution example. + +HTML Widget +~~~~~~~~~~~ + +The HTML widget allows to add customized HTML and CSS code to add very custom dynamic elements to the cockpit. This widget supports all HTML5 standard tags and CSS3 properties. + +.. warning:: + + For security reasons no custom Javascript code can be added to html tags. Every tag considered dangerous will be deleted on save by the filter. + +The Edit section of the widget is composed by five tabs: the dataset, HTML editor, style, cross and filters. +In the editor tab is possible to add the code that will be shown in the widget. Clicking on the top expander section in the tab, the one named "CSS" also the CSS editor will be available. + +.. important:: + + A CSS property will be extended to all the classes in the cockpit with the same name, to apply the property only to the current widget use the id prefix shown in the info panel of the CSS editor + +.. figure:: media/image208.png + + HTML widget editor + +In the right side of the editor is possible to take available tags to copy inside the code, those tags will be explained in details in the following paragraphs. Is not possible to add custom JavaScript code inside the html editor, so the available tags are the tools to make the widget dynamic and to use the dataset data. + +The Dataset tab allows the user to select a dataset to make the Widget dynamic and to bind it to dataset data. +After choosing a dataset the list of available columns will be show. Those names will be useful inside the dynamic tags. Here it is also possible to order the dataset according to a column and to select the ordering type (ascending or descending). + +.. figure:: media/image209.png + + Dataset selection + +By clicking on the icon |image302| of a specific column the dataset will be ordered by that column by default by ascending order. In order to select the descending ordering type you have to click another time on the icon (the icon will be now like this |image303|). + +.. |image302| image:: media/image302.png + :width: 30 + +.. |image303| image:: media/image303.png + :width: 30 + +**Available Tags** + +``[kn-column='COLUMN-NAME' row='COLUMN-ROW-NUMBER' aggregation='COLUMN-AGGREGATION' precision='COLUMN-DECIMALS']`` + +The ``kn-column`` tag is the main dynamic HTML Widget tool, it allows to select a column name from the selected dataset and to print its value. The value of the kn-column attribute should be the name of the column value you want to read in execution. + +The **row** attribute is optional and is a number type attribute. If no row is selected the first row column value will be shown. + +The **aggregation** attribute is optional and is a string type attribute. If inserted the value shown will be the aggregation of all column rows values. The available aggregations are: AVG|MIN|MAX|SUM|COUNT_DISTINCT|COUNT|DISTINCT COUNT. + +The **precision** attribute is optional and is a number type attribute. If added and if the result value is a number, the decimal precision will be forced to the selected one. + +``[kn-parameter='PARAMETER-NAME']`` + +The kn-parameter tag is the tool to show a dataset parameter inside the widget execution. The value of the kn-parameter attribute should be the name of the set attribute. + +``[kn-calc=(CODE-TO-EVALUATE) precision='VALUE-PRECISION']`` + +The ``kn-calc`` tag is the tool to calculate expressions between different values on widget execution. Everything inside the brackets will be evaluated after the other tags substitution, so will be possible to use other tags inside. + +The **precision** attribute is optional and is a number type attribute. If added and if the result value is a number, the decimal precision will be forced to the selected one. + +``
... REPEATED-CONTENT ...
`` + +The ``kn-repeat`` attribute is available to every HTML5 tag, and is a tool to repeat the element for every row of the selected dataset. + +This attribute is naturally linked to ``kn-column`` tag. If inside a ``kn-column`` tag without a row attribute is present, the ``kn-repeat`` will show the column value for every row of the dataset. + +Inside a ``kn-repeat`` is possible to use the specific tag [kn-repeat-index], that will print the index of the repeated column row. + +The **limit** attribute is optional and is a number type attribute. If added the number of row repeated will be limited to the selected number. If no limit is provided just the first row will be returned. If you want to get all records, you can set it to -1, but be careful because big datasets can take a while to load completely. + +``
...
`` + +The ``kn-if`` attribute is available to every HTML5 tag and is a way to conditionally show or hide an element based on some other value. The attribute content will be evaluated after the other tags substitution, so will be possible to use other tags inside. If the evaluation returns true the tag will be shown, otherwise it will be deleted from the execution. + +``
...
`` + +The ``kn-cross`` attribute is available to every HTML5 tag and is a way to make the element interactive on click. This attribute generates an on click event on the element to open the cross navigation set. If there is no cross navigation set this tag will not work. + +``
...
`` + +The ``kn-preview`` attribute is available to every HTML5 tag and is a way to make the element interactive on click. This attribute generates an on click event on the element to open the dataset preview dialog. The attribute value will be the *dataset label* of the dataset that you want to open. If a dataset is not specified the cockpit will use the one set for the widget. If no dataset has been set and the attribute has no value this tag will not work. + +``
...
`` + +The ``kn-selection-column`` attribute is available to every HTML5 tag and is a way to make the element interactive on click. This attributes generates an on click event on the element to set the chosen column and value in the cockpit selections. The default will use as a selection the first row value for the column. + +The **kn-selection-value** attribute is optional and will add a specific value to the column selection. + +``[kn-variable='VARIABLE-NAME' key='VARIABLE-KEY']`` + +The ``kn-variable`` tag is the tool to read the runtime value of one of the defined variables. It will change depending on the current value and can be used inside kn-if and kn-calc. + +The **key** attribute is optional and will select a specific key from the variable object if the variable is "Dataset" type, returning a specific value instead of a complete dataset. + +.. warning:: + **Banned Tags** + In order to avoid Cross-site scripting and other vulnerabilities, some tags are *not allowed* and will automatically be removed by the system when saving the cockpit: + +- ```` +- ```` +- ```` + +If you need to simulate a button behaviour use a div (or another allowed tag) and replicate the css style like in the following example: + +.. code-block:: html + :linenos: + +
Buttonlike div
+ +.. code-block:: css + :linenos: + + .customButton { + border: 1px solid #ccc; + background-color: #ededed; + cursor: pointer; + } + .customButton:hover { + background-color: #d8d8d8; + } + + + +.. warning:: + **Whitelist** + Base paths to external resources (images, videos, anchors, CSS files and inline frames) must be declared within ``TOMCAT_HOME/resources/services-whitelist.xml`` XML file inside Knowage Server, otherwise those external links will be removed by the system. This whitelist file contains safe and trusted websites, to restrict end users of providing unsafe links or unwanted web material. Knowage Server administrator can create or edit it (directly on the file system) to add trusted web sites. Here below you can see an example of ``services-whitelist.xml`` file; as you can see, its structure is quite easy: ``baseurl`` attributes refer to external services, ``relativepath`` must be used for Knowage Server internal resources instead: + + +.. code-block:: xml + :linenos: + + + + + + + + + + + + + + +Like other widgets the "Style" tab and the "Filters" tab are available in order to set the general style options for the widget and to filter the results displayed in the HTML widget. + +Map Widget +~~~~~~~~~~~ + +The Map Widget is useful when a user needs to visualize data related to a geographic position. The widget supports multiple layers, one for every dataset added to widget configuration, and one data field for every layer: the user can switch on-the-fly between all data available on the layer. + +.. figure:: media/image475.png + + Map widget. + +In Map Widget configuration a user can add and remove layers, set the format of the spatial attribute to use and specify the attributes to display on map and on the detail popup: + + .. figure:: media/image476.png + + Map widget configuration. + +Every dataset with a spatial attribute is eligible to become a layer in map widget. Only one layer of the widget can be susceptible to user selection: that layer will be the only one with **Target** slide set to on. For each layer a user can also specify its default visibility with **Default visibile** slide. Enabling **Static** switch on a layer make it visible and non clickable, useful when a user wants a fixed background layer with dynamic data from a dataset. With buttons |image478| and |image479| the user can set the metadata and the layer style respectively. + +.. |image478| image:: media/image478.png + :height: 26 + +.. |image479| image:: media/image479.png + :height: 26 + +In layer's metadata, the user can add calculated fields (more on that later) and set the spatial attribute of the dataset that will be used to display a markers on the map. Actually, many spatial attribute types are supported: + +- String format: where the value specify two decimal numbers representing latitude and longitude separated by a space; +- JSON: where the value is a text string in `GeoJSON `_ format; +- WKT: where the value is a text string in `Well-known Text `_ format; + +.. important:: + **Geographic coordinates format** + + For every format above user have to specify what is the format of geographic coordinate: user have to specify if latitude comes first or vice versa. + +The first field listed in metadata is the spatial attribute and Knowage let the user to set if the spatial attribute need to be part of the aggregation or not: this let the user to create special query; for example, you may need to just list all the records of a dataset without any aggregations and in this case you can simply uncheck all the aggregate by checks and clean up the aggregation function for the spatial attribute; another example is where the spatial attribute at database side is of a special type like CLOB on Oracle, in that case the user cannot use that field for the aggregation but the user can exclude the spatial attribute from the aggregation, converting the field to measure and setting an aggregation function. + +Every field of the dataset, except for the spatial one, can have a custom alias to show on map widget: just double click the label to edit it. A user can also specify if a field have to be shown on detail popup. + +For measures a user could specify the aggregation function, if it has to be shown on detail popup and if it has to be shown on map: at least one field has to be shown on map. + +For attributes a user could specify if it has to be shown on detail popup or if it has to be show as a filter: in that case, the attribute will be available in the control panel with its all distinct values to let the user to have an immediate evidence of which markers have the selected value for the measure + +The user could also select if a specific attribute should be displayed in the tooltip that will be shown when the user hovers a specific feature on the map. + +The 3-dots-menu on the right of each column of the dataset contains additional functionalities: for measures, for example, there is the possibility to specify thresholds. + +The threshold menu open a dialog where the user can customize marker color by value range: that's very useful when a user wants to immediately identify a marker by it's value. + + .. figure:: media/image482.png + + Threshold dialog. + +For all the attributes that are filters, a user could select the relative value from the control panel: + + .. figure:: media/image499.png + + Filter selection. + +As said, Map widget supports calculated fields, a way for a user to calculate additional data to show on map or to display into popup detail: + + .. figure:: media/image503.png + + Add calculated field button in layer's metadata. + +From the calculated field's dialog a user can combine measures and operations to add more data to the layer. The user can use a SQL-like syntax to create a statement that describe the new calculated field: + + .. figure:: media/image504.png + + Calculated Field's dialog. + +The newly calculated field added by the user is shown as a measure in layer's dataset: from the 3-dots menu on the right of the field a user can update or delete the calculated field. + + .. figure:: media/image505.png + + The 3-dots menu on calculated field. + +For every layer, a user can specify the way the data will be displayed on map: the user can choose between a markers, cluster, heatmaps and choroplet. + +.. figure:: media/image477.png + + Style configuration for every layer. + +For marker there are multiple choices between a user can select. The first one is the standard marker, where a user can select only the marker color: + +.. figure:: media/image483.png + + Standard marker configuration. + +The second possibility is to use a custom color and custom scale with a custom marker, for example and icon available in Font Awesome catalog: + +.. figure:: media/image484.png + + Custom marker configuration. + +A user can also use an image from Knowage media as a marker: + +.. figure:: media/image485.png + + Marker from Knowage images. + +Finally a user can use an image from external URL as a marker: + +.. figure:: media/image486.png + + Marker from Knowage images. + +Cluster visualization renders circles of different size where every circle aggregating positions by relative values. A user can zoom in to disaggregate the cluster until he see the single data. For this type of visualization, a user can set size and color of the circle and the size and the color of the font used to display the aggregated value: + +.. figure:: media/image487.png + + Cluster configuration. + +When heatmap is selected, a user can display values by areas colored by a color range from green to red where the values are respectively lower and higher. Setting the radius and the blur, a user can specify the scale of the areas and the scale of the blur around it: + +.. figure:: media/image488.png + + Heatmap configuration. + +The choroplet visualization allows a user to precisely associate values to areas, very useful when spatial attribute specify a geometry instead of a single point. The classes method specify the subdivision algorithm and the classes number specify how many subdivision to make; the colors specify the start and the end of the range color that will follow the same range of the values: + +.. figure:: media/image489.png + + Choroplet configuration. + +Discovery Widget +``` + +.. figura:: media/image480.png + +El widget de descubrimiento se utiliza para usar y navegar fácilmente en un conjunto de datos Solr utilizando la agregación de facetas y los resultados de una tabla. +Para realizar búsquedas, agregaciones utilizando facetas, etc., después de seleccionar el conjunto de datos Solr es posible elegir los campos que deben mostrarse como resultado. +El resultado de la tabla también se puede configurar para mostrar un conjunto limitado de campos, abra el modo de edición: + +.. figura:: media/image481.png + +**Configuración** + +La ficha configuración contiene la gestión de los 3 elementos que componen una directiva: +\- Tabla de datos: habilitada por defecto es la cuadrícula que contiene los datos. Puede elegir el número de elementos por página. +\- Facetas: si está habilitado aparecerá el panel lateral con las facetas. También es posible configurar las opciones de facetas: +\- *Habilitar la selección en facetas*, si está habilitado, un usuario hace clic en las facetas arrojará una selección de cabina en lugar de simplemente filtrar la tabla. +\- *cerrado de forma predeterminada*, si está habilitado, las facetas serán visibles como grupos cerrados de forma predeterminada. +\- *facetas ancho de columna*, esta configuración permite elegir la dimensión de la columna de facetas en valores px, rem o porcentaje. +\- *número máximo de facetas*, esta configuración permite elegir el número máximo de facetas visibles para cada campo. +\- Búsqueda de texto: si está habilitada aparecerá una barra de búsqueda en la parte superior del widget. Es posible establecer una búsqueda predeterminada para la inicialización del widget. + +.. figura:: media/image481b.png + +**Importante** Las opciones "mostrar columna" y "mostrar facetas" son solo del lado frontend. No afectan a la consulta Solr de backend real, el widget de descubrimiento buscará todos los campos aunque se omitan el frontend. + +**Ordenación de columnas de facetas** + +.. figura:: media/image491.png + +Es posible cambiar el orden de las columnas de facetas, por ejemplo, si existe la necesidad de mover hacia arriba un campo. + +Como se muestra en este ejemplo, "aggregazione" debe mostrarse arriba, simplemente vaya a la sección de widgets de edición: + +.. figura:: media/image492.png + +Y cambie el orden de las columnas arrastrando el campo a la posición correcta. + +.. figura:: media/image491b.png + +**Cambio del formato de fecha para las columnas de fecha de la tabla de detección** + +También es posible cambiar el formato utilizado para mostrar las columnas de fecha dentro de la tabla de descubrimiento: +Para hacer eso, haga clic en el estilo de los campos de columnas de fecha en modo de edición + +.. figura:: media/image493.png + +Y cambie la propiedad "formato de fecha" + +.. figura:: media/image494.png + +.. figura:: media/image495.png + +Python/R Widget + +``` + +The Python/R widgets allow to directly embed Python or R scripts inside the cockpit in order to create advanced custom analytics. + +In the editor tab it is possible to add the script that will be sent to the execution engine. + +.. figure:: media/PythonEditor.png + + +Before writing the code it is necessary to specify the **type** of the output produced by the script. +Knowage has support for three different output types: + +- Image +- HTML + +It is also necessary to specify the name of the file in which the script will save its output. + +The Dataset tab allows the user to select a dataset that will be accessible directly from the code. +After choosing a dataset the list of available columns will be shown. Here it is also possible to order the dataset according to a column and to select the ordering type (ascending or descending). + + +.. figure:: media/DatasetTab.png + + Dataset selection + +Once a dataset has been choosen, it will be possible to access it directly from the code via a **dataframe** variable. +This variable will have the same name of the dataset label. + +The Environment tab allows the user to choose among a list of available Python/R evironments previously defined inside the **Configuration Management**. +To support this kind of choice a list of available libraries is displayed for each selected environment. + +.. figure:: media/EnvironmentTab.png + + Environment selection + +Inside Python and R scripts it is possible to access analytical drivers by the usual placeholder syntax *$P{}*. + +.. warning:: + **This widget is sensible to associative logic, meaning that the widget is updated every time that an association is changed, but it DOES NOT trigger associative logic itself.** + +Custom Chart Widget +``` + +.. figura:: media/image500.png + +El gráfico personalizado permite al usuario incrustar directamente código html, css y js utilizando una biblioteca de gráficos externa compatible e integrándose con datos e interacciones de Knowage utilizando api personalizada. + +Este widget solo estará disponible si el *crear widget de gráfico personalizado* se establece para el rol especificado. + +La sección Editar del widget está compuesta por cinco pestañas: dataset, editor, estilo, cruz y filtros. + +El **ficha Conjunto de datos** permite seleccionar un conjunto de datos específico para usarlo como refferral para la API. Una vez que se haya seleccionado el conjunto de datos, aparecerá una tabla con la lista de columnas a continuación. +En la tabla será posible cambiar el alias de columna, la agregación de columnas para medidas y eliminar columnas que interactúan con la línea de columna seleccionada. +Haciendo clic en *agregar columna* o *agregar campo calculado* en la parte superior aparecerá una ventana emergente que permite elegir una de las columnas del conjunto de datos para agregar o insertar la fórmula de campo calculada. + +.. figura:: media/image501.png + +El **Pestaña Editor** permite insertar código personalizado y se divide en tres componentes: CSS, HTML, JavaScript. + +.. figura:: media/image502.png + +El componente CSS permite insertar clases css que serán utilizadas por el código HTML del widget. También es posible usar *@import* si la url referida está dentro de la lista blanca. + +El componente HTML permite insertar etiquetas HTML para crear una estructura para alojar el gráfico personalizado e información estructural adicional. + +El componente JavaScript es la sección de código y permite insertar el código de gráfico personalizado, el código Javascript personalizado y el uso de la API. + +Para usar la api, la palabra clave es **almacén de datos**. datastore es un objeto que contiene los datos reales; tiene métodos para iterar sobre los resultados y obtener todos los valores, como la contraparte de Java, además de algunos otros métodos como los siguientes: + +**getDataArray** + +| Devuelve: *matriz de datos* +| parámetros: *función de usuario personalizada* +| ejemplo: + +.. code-block:: javaScript +:linenos: + + datastore.getDataArray(function(record){ + return { + name: record.city, + y: record.num_children_at_home + } + }) + +| resultado: + +.. code-block:: javaScript +:linenos: + + [ + { + name:'New York', + y: 5 + }, + { + name:'Boston', + y: 3 + } + ] + +**getRecords** + +| devuelve: matriz de objetos; Cada objeto tiene nameOfDsColumn: valor +| parámetros: sin parámetros +| ejemplo: + +.. code-block:: javaScript +:linenos: + + datastore.getRecords() + +| resultado: + +.. code-block:: javaScript +:linenos: + + [ + { + city:'New York', + total_children: 5, + country: 'USA' + }, + { + name:'Boston', + total_children: 3, + country: 'USA' + + } + ] + +**getColumn** + +| devuelve: matriz de *único* valores para una columna del conjunto de datos +| parámetros: nombre de columna del conjunto de datos +| ejemplo: + +.. code-block:: javaScript +:linenos: + + datastore.getColumn('country') + +| resultado: + +.. code-block:: javaScript +:linenos: + + ['USA','Mexico','Canada'] + +**getSeriesAndData** + +| devuelve: matriz de series con datos para cada serie +| parámetros: nombre de serie/medida, función de usuario personalizada +| ejemplo: + +.. code-block:: javaScript +:linenos: + + datastore.getSeriesAndData('PRODUCT_FAMILY',function(record){ + return { + y: record.UNIT_SALES, + name: record.QUARTER + } + }) + +| resultado: + +.. code-block:: javaScript +:linenos: + + [ + { + name:'Drink', + data: [ + { + y: 5000, + name: 'Q1' + }, + { + y: 7000, + name: 'Q2' + + } + ] + }, + { + name:'Food', + data: [ + { + y: 6000, + name: 'Q1' + }, + { + y: 4000, + name: 'Q2' + + }, + { + y: 3000, + name: 'Q3' + + } + ] + } + ] + +**ordenar** - servicio de ordenación angular (la ordenación se ejecuta en el lado del cliente) + +| devuelve: almacén de datos ordenado por columna/s del conjunto de datos +| parámetros: nombre de columna del conjunto de datos +| opcional: objeto de tipo de ordenación {columna:'asc/desc'} +| ejemplo1: + +.. code-block:: javaScript +:linenos: + + datastore.sort('STORE_ID') //by default, it is asc + OR: + datastore.sort({'STORE_ID':'asc'}) + +**filtro** - Servicio de filtro angular (el filtrado se ejecuta en el lado del cliente) + +| devuelve: almacén de datos filtrado por algún valor para la columna o columnas del conjunto de datos +| params: objeto que contiene los nombres de columnas del conjunto de datos para las propiedades -> valor que se va a filtrar, un booleano opcional para habilitar la comparación estricta (false como predeterminado) +| ejemplo: + +.. code-block:: javaScript +:linenos: + + datastore.filter({'QUARTER':'Q1','STORE_ID':'1'}, true) + +**jerarquía** + +| devuelve: objeto de jerarquía con sus funciones y árbol +| params: objeto que contiene niveles de propiedad -> matriz de nombres de columnas del conjunto de datos +| opcional: mismo objeto con medidas de propiedad opcionales -> objeto que contiene los nombres de columnas del conjunto de datos para properites -> función de agregación (suma, mín, máx.) +| ejemplo: + +.. code-block:: javaScript +:linenos: + + var hierarchy = datastore.hierarchy({'levels':['QUARTER','PRODUCT_FAMILY'],'measures': {'UNIT_SALES':'SUM'}}) + +| resultado: + +.. code-block:: javaScript +:linenos: + + [ + { + "name": "Q1", + "children": [ + { + "name": "Non-Consumable", + "children": [], + "UNIT_SALES": 7.4571 + }, + { + "name": "Food", + "children": [], + "UNIT_SALES": 12 + } + ], + "UNIT_SALES": 19.4571 + }, + { + "name": "Q2", + "children": [ + { + "name": "Non-Consumable", + "children": [], + "UNIT_SALES": 9.9429 + }, + { + "name": "Food", + "children": [], + "UNIT_SALES": 7.2 + } + ], + "UNIT_SALES": 17.1429 + } + ] + +**getChild** + +| devuelve: nodo de jerarquía (nodo es objeto Node) +| parámetros: índice de hijo en jerarquía +| ejemplo: + +.. code-block:: javaScript +:linenos: + + hierarchy.getChild(0) + +| resultado: + +.. code-block:: javaScript +:linenos: + + { + "name": "Q1", + "children": [ + { + "name": "Non-Consumable", + "children": [], + "UNIT_SALES": 7.4571 + }, + { + "name": "Food", + "children": [], + "UNIT_SALES": 12 + } + ], + "UNIT_SALES": 19.4571 + } + +**getLevel** + +| devuelve: matriz de nodos de jerarquía en un nivel específico +| parámetros: índice de nivel en jerarquía +| ejemplo: + +.. code-block:: javaScript +:linenos: + + hierarchy.getLevel(0) + +| resultado: + +.. code-block:: javaScript +:linenos: + + [ + { + "name": "Q1", + "children": [ + { + "name": "Non-Consumable", + "children": [], + "UNIT_SALES": 7.4571 + }, + { + "name": "Food", + "children": [], + "UNIT_SALES": 12 + } + ], + "UNIT_SALES": 19.4571 + }, + { + "name": "Q2", + "children": [ + { + "name": "Non-Consumable", + "children": [], + "UNIT_SALES": 9.9429 + }, + { + "name": "Food", + "children": [], + "UNIT_SALES": 7.2 + } + ], + "UNIT_SALES": 17.1429 + } + ] + +*nodo* es una instancia del objeto Node. Tiene funciones convenientes para explorar el nodo: + +.. code-block:: javaScript +:linenos: + + var node = hierarchy.getChild(0) + +| resultado: + +.. code-block:: javaScript +:linenos: + + { + "name": "Q1", + "children": [ + { + "name": "Non-Consumable", + "children": [], + "UNIT_SALES": 7.4571 + }, + { + "name": "Food", + "children": [], + "UNIT_SALES": 12 + } + ], + "UNIT_SALES": 19.4571 + } + +**getValue** + +| devuelve: el valor de una medida para el nodo secundario (nodo) de una jerarquía específica +| parámetros: nombre de las medidas del conjunto de datos +| ejemplo: + +.. code-block:: javaScript +:linenos: + + node.getValue('UNIT_SALES') + +| Resultado: 19.4571 + +**getChild** + +| devuelve: el hijo de un nodo específico +| parámetros: índice del hijo de los nodos +| ejemplo: + +.. code-block:: javaScript +:linenos: + + node.getChild(0) + +| resultado: + +.. code-block:: javaScript +:linenos: + + { + "name": "Non-Consumable", + "children": [], + "UNIT_SALES": 7.4571 + } + +**getParent** + +| devuelve: un nodo primario de un hijo específico +| parámetros: sin parámetros +| ejemplo: + +.. code-block:: javaScript +:linenos: + + node.getChild(0).getParent() + +| resultado: + +.. code-block:: javaScript +:linenos: + + { + "name": "Q1", + "children": [ + { + "name": "Non-Consumable", + "children": [], + "sales": 7.4571 + }, + { + "name": "Food", + "children": [], + "sales": 12 + } + ], + "sales": 19.4571 + } + +**getNiños** + +| devuelve: una matriz de elementos secundarios del nodo +| parámetros: sin parámetros +| ejemplo: + +.. code-block:: javaScript +:linenos: + + node.getChildren() + +| resultado: + +.. code-block:: javaScript +:linenos: + + [ + { + "name": "Non-Consumable", + "children": [], + "sales": 7.4571 + }, + { + "name": "Food", + "children": [], + "sales": 12 + } + ] + +**getSiblings** + +| devuelve: una matriz de hermanos de nodo a un hijo específico +| parámetros: sin parámetros +| ejemplo: + +.. code-block:: javaScript +:linenos: + + node.getChild(0).getSiblings() + +| resultado: + +.. code-block:: javaScript +:linenos: + + [ + { + "name": "Non-Consumable", + "children": [], + "sales": 7.4571 + }, + { + "name": "Food", + "children": [], + "sales": 12 + } + ] + +**Variables** + +| devuelve: un objeto clave/valor con todas las variables y valores declarados +| parámetros: sin parámetros +| ejemplo: + +.. code-block:: javaScript +:linenos: + + var myvariables = datastore.variables; + +| resultado: + +.. code-block:: javaScript +:linenos: + + { + variableCity: 'New York', + variableNum: 100 + } + +**perfil** + +| devuelve: un objeto clave/valor con todos los atributos de perfil declarados para el usuario +| parámetros: sin parámetros +| ejemplo: + +.. code-block:: javaScript +:linenos: + + var user = datastore.profile; + +| resultado: + +.. code-block:: javaScript +:linenos: + + { + name: 'My Name', + tenant: 'Knowage', + customProfileAttribute: 'Test value', + role: 'user' + } + +También es posible interactuar con los otros widgets de la cabina, para ello es posible utilizar el **clickManager**: + +.. code-block:: javaScript +:linenos: + + datastore.clickManager(columnName, columnValue); + +| Este método se puede agregar en cualquier lugar donde el código esté administrando un evento de clic y notificará a Knowage sobre el +interacción. +| El caso predeterminado (si no se establece la navegación cruzada o la navegación previa) arrojará una selección con el +nombre de columna del conjunto de datos y valor de columna establecidos en el método. +| Si se ha establecido una navegación cruzada o una vista previa en la pestaña cruzada, estos tendrán prioridad en la selección y +lanzar la interacción establecida. Los valores dinámicos utilizados serán los establecidos en los argumentos del método. + +.. importante:: +**Bibliotecas de gráficos** + + As a default Knowage supports natively Chart.js (version 1.0.2) for the Community edition and Highcharts.js (version 7.1.1) for the Enterprise Edition. In CE and EE, Knowage supports d3.js library (version 3.5.5). It is possible also to include other libraries adding the CDN script tag in the html Editor. + Be aware that url not set in the whitelist will be deleted on save. + To use this import use the kn-import tag like the following example: + +.. code-block:: html +:linenos: + + + +.. advertencia:: +**Lista blanca** +Por razones de seguridad, no se puede agregar ningún código Javascript peligroso a las etiquetas html. Cada etiqueta considerada peligrosa será eliminada al guardar por el filtro. +Las rutas base a recursos externos (imágenes, vídeos, anclajes, archivos CSS y marcos en línea) deben declararse dentro de `TOMCAT_HOME/resources/services-whitelist.xml` ARCHIVO XML dentro de Knowage Server, de lo contrario, el sistema eliminará esos enlaces externos. Este archivo de lista blanca contiene sitios web seguros y confiables, para restringir a los usuarios finales de proporcionar enlaces inseguros o material web no deseado. El administrador de Knowage Server puede crearlo o editarlo (directamente en el sistema de archivos) para agregar sitios web de confianza. A continuación puedes ver un ejemplo de `services-whitelist.xml` archivo; como ves, su estructura es bastante fácil: `baseurl` atributos se refieren a servicios externos, `relativepath` en su lugar, debe utilizarse para los recursos internos de Knowage Server: + +.. code-block:: xml +:linenos: + + + + + + + + + + + + + + + +Al igual que otros widgets, la pestaña "Cruz", "Estilo" y la pestaña "Filtros" están disponibles para establecer las opciones de estilo generales para el widget y filtrar los resultados que se muestran en el widget HTML. + +Navegación cruzada + +``` + +.. warning:: + **Cross tab is only for technical users** + + Due to the fact that parameters can only be managed by technical user the cross navigation cannot be implemented by the final user. + +All widgets (except selector and active selections) have the Cross tab available, that allows the user to interact with the widget in different ways: +- setting a Cross-navigation between different documents +- setting a Preview of a specific dataset to popup +- opening an external link +The interactions are mutually exclusive, so just one type can be chosen for every widget. + + +**Cross-navigation** + +The cross-navigation gives the possibility to connect two documents clicking on a widget as a starting point, opening the second one as arrival and showing the breadcrumbs on top. + +.. figure:: media/image212.png + + Table widget cross-navigation configuration. + +To enable one first of all is necessary to set a cross navigation inside the "cross-navigation definition" functionality. +There is possible to set the starting/arrival point and to set the connection between different output/input parameters. + +After this passage you will have the possibility to enable the cross-navigation in the tab and choose the user interaction that will start the navigation, if more than one are available. + +The most complex example is the table widget cross-navigation, because it allows 3 different interactions: + +- *Click on the whole row*, where the interaction will start clicking on any row +- *Click on a single column*, where the editor will choose a specific column that will start the interaction (the user will see the column values underlined) +- *Click on an icon*, where the editor will choose an icon positioned to the right side that will start the interaction. + +Once the interaction has been chosen you will be able to select the cross-navigation created before. If you created more than one related to that document +you will be able to choose between them. If you leave this field blank the user will be able to choose that himself. + +**Preview** + +.. figure:: media/image214.png + + Table widget preview configuration. + +The preview configuration is very similar to the cross-navigation one. +First of all you will need to enable the navigation using the switch button. +After you will need to choose an interaction type and a target dataset. +the selected dataset will be opened in a popup window but, if you check the "Direct download" property you will be able to get the dataset preview directly in the download list. + +.. figure:: media/image216.png + + Preview example. + +**Cross and Preview Parameters** + +.. figure:: media/image213.png + + Parameters example. + +Both cross-navigation and preview navigation share the parameters management. +If one or more output parameters are available, you will find the list below the navigation page. +You can choose which values to use clicking on the checkbox at the right side of the name, than you will have the possibility to choose between different modes to get the value: + +- *Static*, entering a static value +- *Dynamic*, passing the value of the column at the selected row (or passing the column name if *Selected Column Name* is chosen) +- *Selection*, passing the current value of the selection for the specified dataset and column. Warning: the selection is not triggered clicking on the navigation, so to pass this value the selection must already be present. + +Once the user will click on the widget, those parameters will be evaluated before the navigation. + + +**Link** + +The link configuration is very similar to the cross-navigation one too. +First of all you will need to enable the link navigation using the switch button. +Then you will be able to create one or more link navigations. +You will need to choose an interaction type and a base url. The base url will be the url opened by the user click. +You can also decide the type of link between the opening of a new page or the document replace opening in the same page. + +.. figure:: media/image215.png + + Link configuration with JSON parameter example. + +**Link Parameters** + +The link parameters are different from the previous because they will be used to make the baseurl selected more precise. +The resulting example url will be something similar: http://www.knowage-suite.com?**parameter1**=value&**parameter2**=value2 + +To do so you will have to create and name different parameters, the selected name will be the one used in the url construction. +You can choose how to get the parameter value with the following modes: + +- *Static*, entering a static value +- *Dynamic*, passing the value of the column at the selected row (or passing the column name if *Selected Column Name* is chosen) +- *Selection*, passing the current value of the selection for the specified dataset and column. Warning: the selection is not triggered clicking on the navigation, so to pass this value the selection must already be present. +- *Analytical Driver*, passing a page parameter (input driver) +- *JSON*, passing an escaped JSON inside the url parameter. You can use the editor to create the desired JSON and use the placeholder to set the value at runtime. The placeholders are the usuals *$F{field}* for the fields, *$P{parameter}* for the parameters, *$V{variable}* for the variables. +- *JWT*, passing the JWT token of the user + +Widget properties +``` + +Una vez que se han implementado uno o más widgets (mencionados anteriormente), el usuario técnico tiene algunas opciones más que exploran el icono disponible en la esquina superior derecha del widget, como se destaca en la Figura a continuación. + +.. figura:: media/image192.png + + Widget properties. + +Aquí el usuario puede: + +* mueva el widget en el área de la cabina a conveniencia; +* modificar su dimensión; +* eliminarlo; +* activar la interacción en el clic del widget con los demás; +* activar la actualización de los datos del widget debido a la interacción con otros widgets. + +Al ejecutar la cabina en modo de visualización, el usuario también tiene algunas opciones más para widgets. Para todos los widgets, el usuario puede usar el icono |image197| para expandir el widget a todas las páginas y utilizar el icono |image198| para reducirlo de nuevo. También hay dos nuevas opciones de widgets: usar el icono |image300| es posible capturar la captura de pantalla del widget y hacer clic en el icono |image301| los datos trazados en un gráfico o mostrados en una tabla o tabulación cruzada se exportan en un archivo de Excel. + +.. |imagen197| imagen:: media/image193.png +:ancho: 30 + +.. |imagen198| imagen:: media/image194.png +:ancho: 30 + +.. |image300| imagen:: media/image300.png +:ancho: 30 + +.. |image301| imagen:: media/image301.png +:ancho: 30 + +Los widgets de gráfico están dotados de una opción adicional que permite al usuario cambiar el tipo de gráfico, como puede ver en la figura a continuación. + +.. figura:: media/image195.png + + Change chart type button. + +Refiriéndose a la figura a continuación, los tipos de gráficos disponibles son: paralelo, dispersión, nube de palabras, línea, radar, barra y pastel. + +.. figura:: media/image196.png + + Available chart types. + +Sin embargo, preste atención al hecho de que cuando se han utilizado funciones de agrupación, el tipo de gráfico de cambio puede no informar el mismo nivel de agregación. De hecho, no todos los tipos de gráficos permiten la función de agrupación. Consulte Tipos de gráficos en detalle para obtener más información sobre la configuración de cada tipo de gráfico. Preste también atención cuando un gráfico de dos series se conecta con uno de una sola serie. Por ejemplo, el gráfico paralelo funciona solo cuando (al menos) se han establecido dos series, mientras que la nube de palabras funciona con una sola serie. + +## Configuración general + +Esta opción permite al usuario gestionar todos los ajustes generales de la cabina que vamos a describir a través de imágenes de la interfaz. Haciendo clic en el botón **Configuración general** se abre la ventana de la figura siguiente. Esto contiene el **Configuración general** y el **Estilo de widget** pestaña. + +.. figura:: media/image197.png + + General configuration window. + +Editando los campos de la primera pestaña puede agregar o cambiar el nombre y / o la descripción de su cabina; además, aquí puede elegir el color de la hoja o una imagen de fondo y su tamaño. En particular, para agregar una imagen de fondo para las hojas, primero debe agregar la imagen al catálogo del widget de imagen y luego copiar el enlace de la imagen. También es posible decidir habilitar el menú y las funcionalidades de los widgets cuando el documento se ejecuta en modo de visualización o deshabilitar la funcionalidad de captura de pantalla para cada widget. + +La segunda pestaña (Figura a continuación) permite configurar algunas opciones de estilo de la cabina, como bordes, sombras, títulos y color de fondo. + +.. figura:: media/image198.png + + Widget style tab. + +La tercera pestaña permite anular las propiedades css comunes para toda la cabina. +El editor resaltará posibles errores de sintax. + +.. figura:: media/image497.png + + Css editor tab. + +## Configuración de datos + +Esta función administra el almacenamiento y el uso de datos. De hecho, aquí existe la posibilidad de guardar datos en caché, crear asociaciones entre conjuntos de datos, crear índices en datos almacenados en caché, programar la frecuencia de actualización (de datos), etc. Refiriéndose a la siguiente figura, la función se implementa a través de varias pestañas: el **Fuente** , el **Asociaciones** , el **Índices**el **Frecuencia** y el **Plantilla** pestaña. + +.. \_dataconfigwindow: +.. figura:: medios/image199\_b.png + + Data configuration window. + +Fuente + +``` + +The Source tab is split into two areas. On the left side the user can find the list of those dataset that are currently used by the cockpit. Here it is possible to add new dataset that will be passed to widgets. In other words, datasets inserted in this area will be listed in the dataset combobox of widgets like the Table, the Pivot Table and the Chart one. Note that the user can delete datasets as well. + +Parametric sources management +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If the user is adding a parametric dataset the window will exhibit them in an expandable box right below. It is also mandatory to give default values or to associate proper drivers to the document to secure its correct execution. By the way, a final user has no access to parametric dataset and he/she cannot handle analytical drivers, therefore **parametric sources can be managed only by an admin user**. We stress that the user must also type the driver name in the field box as highlighted in Figure below. You can type it manually or use the look up just aside the parameter line. + +.. figure:: media/image200.png + + Dataset management. + +On the right side of the window the user finds the list of external documents that can be added to the cockpit (through Document widgets), or as well as for the dataset case, of documents that are already in use in (previously set) Document widgets. In the occurrence of Associations parametric documents, parameter boxes are shown below. Note that it is mandatory to link them to analytical drivers (previously hooked to the document) or be assigned a fixed (default) value. + +Associations +``` + +Si su objetivo es mostrar datos de un único conjunto de datos, no es necesario definir ninguna asociación. *Las asociaciones deben establecerse dentro del diseñador cuando los widgets se crean en diferentes conjuntos de datos*. Las asociaciones se pueden establecer con los elementos: columnas de conjunto de datos, parámetros de conjunto de datos y parámetros de documento. Tenga en cuenta que para implementar una asociación, el usuario debe tener al menos una columna. Mostramos algunos ejemplos a continuación. + +La siguiente figura muestra la asociación entre dos conjuntos de datos. En este caso, el usuario debe detectar un campo del primer conjunto de datos, el mismo campo (en términos de valores) en el otro. La relación aparecerá justo debajo. Haga clic en el botón Guardar para confirmar la asociación. Si las asociaciones se basan en varias columnas, el usuario debe agregarlas una por una. + +.. \_assocbetweendatacolum: +.. figura:: media/image201.png + + Associations between dataset columns. + +El mismo procedimiento se puede realizar en el caso de las columnas del conjunto de datos y los parámetros del conjunto de datos, como se muestra a continuación. + +.. figura:: media/image202.png + + Associations between dataset column and dataset parameter. + +Otro ejemplo se proporciona en la figura a continuación. Aquí se realiza la asociación entre una columna de frecuencia del conjunto de datos y un parámetro de documento. + +.. figura:: media/image203.png + + Associations between dataset column and document parameter. + +Una vez que haya definido las asociaciones, tan pronto como actualice un widget, todos los widgets relacionados se actualizarán simultáneamente en la actualización de datos. + +**Detección automática de fuccionalidad** + +Para configurar correctamente las asociaciones significativas, el usuario debe tener conocimiento de los datos extraídos contenidos en cada conjunto de datos. Sin embargo, puede haber posibles coincidencias entre conjuntos de datos que no son conocidos por el usuario o las columnas utilizadas no son tan similares como se pensaba. Por lo tanto, el usuario puede exigir a Knowage que recupere todas las columnas posibles que coincidan, que informe el porcentaje de valores coincidentes y que tenga conocimiento de otras posibles coincidencias inesperadas. + +En la "Configuración de la cabina de datos" vista en la sección anterior, tenemos el botón "Detección automática" que redirige al usuario a la página de dectect automático. El botón se encuentra en la esquina superior derecha del área de la lista de asociaciones. + +.. figura:: media/image507.png + + Auto Detect button. + +Aquí el usuario puede decidir un porcentaje mínimo de coincidencia que Knowage utilizará para calcular y devolver columnas coincidentes. Por ejemplo, un 20% de similitud significa que los valores contenidos por dos o más columnas de diferentes conjuntos de datos son los mismos al menos para el 20% de ellos. Siguiendo el ejemplo que se muestra en la figura a continuación, podemos leer que entre los tres conjuntos de datos, solo dos de ellos tienen posibles asociaciones. El usuario puede usar una coincidencia de similitud del 100% utilizando el campo "produt_family", lo que significa que las dos columnas contenidas en dos conjuntos de datos diferentes devuelven exactamente la misma lista de valores distintos. O el usuario puede establecer una asociación con una similitud del 75,23% utilizando el campo "the_date", lo que significa que algunos valores de una columna no están contenidos en la otra columna. La longitud mínima permite al usuario especificar el número más bajo de conjuntos de datos a los que se unirán. + +.. figura:: media/image506.png + + Auto Detect page. + +Para seleccionar una de las asociaciones sugeridas, simplemente haga clic en la fila específica y luego en el botón Guardar. Guarde la configuración y guarde el panel. La nueva asociación está lista para ser utilizada. + +Índices + + If you want that cockpit loading be faster, you can create indexes on cached data. This feature is available only for cached dataset. + + If you want to create an index on a column you have to choose that column by clicking. The name of the column will appears in the Indexes List + section of the page. If you want to confirm your choose, click on the save icon. If you want to cancel it, click on the cross icon. After saving + a index you'll see in the list surrounded by a continuous border. + + .. figure:: media/image305.png + + Indexes settings example + + For example, in the figure above index on the column "customer_id" of ALL_CUSTOMERS dataset is already saved. + "store_name" column of "SPARKSQL_STORE" dataset is selected. If you want to create an index on it, you have to save it. + + Frequency + ~~~~~~~~~ + + The Frequency tab defines a schedulation over dataset involved in the associations. An example is supplied in the next figure. This means that associations are activated automatically and data are reloaded according to this feature. In particular, groups of realtime datasets that compose one or more associations can have different update frequencies. We stress that, in order to secure the right document execution, the group frequency do not affect the other ones and each group is reloaded at different times. In addition, realtime dataset that are not involved in any association can have their own frequency. + + .. _frequsettexample: + .. figure:: media/image204.png + + Frequency settings example. + + Variables + ~~~~~~~~~ + + In this tab the user can define the variables that will be available inside the cockpit. + + .. figure:: media/image496.png + + Variables tab + + Every variable needs a name that will be used to call it and get the value, a type and a value. + The available types are the following: + + - Static: a static number or string. + - Dataset: the value of a selected dataset column. If a column is not selected a set of variables key/value will be created using the first two columns of the selected dataset. + - Profile: a set of profile attributes available. (ie. the username) + - Driver: the value of a selected analytical driver. + + The variables will be available inside the widgets with the $V{variablename} format. + + Template + ~~~~~~~~ + + In this tab the user can find the json code (at the current stage of the work) which composes the template. Figure below shows an example. + + .. figure:: media/image205.png + + Template example. + + + Selections + -------------- + + Adding the **Selections** to your widgets, namely the possibility to reload all widget data according to selection made through the click on a specific item of the cockpit (cell value, chart bar, etc.). Moreover, thanks to this functionality the user can reproduce the drill down feature that we introduced in Chapter of Chart. You can check which selections are active on your cockpit at anytime thanks to the **Selection** functionality. In Section 7.1 we already described how to add the “Selection” widget inside the cockpit area. If the user do not wish for the widget to stay visible, selections can still be accessed and managed through the menu configuration bar. Clicking on the “Selection” menu icon you can enter the “Selections” window. Here all selections and associations are listed, as shown in Figure below. The “Delete” button is available just aside each row to let the user to remove that specific selections. Click on the “Cancel” button to exit the window. + + + .. figure:: media/image206.png + + Selection window. + + + Clear cache + --------------- + + The **Clear cache** button lets you realign the data shown in your widget to the ones in your database. When you create your widget and associate your datafields, a photo of data is made and stored in temporary tables. This means that your cockpit will display the same data at each execution until you clean the chace by clicking on the dedicated button and execute the document again. Now your data are refreshed and updated to the one contained in your database at last execution time. As discussed before this button is available also in “Read only” modality. + + Save + -------- + + You can save the cockpit by clicking on the save button in the right-top corner. The document will be saved in the personal folder (technical users) or in the **My Analysis** section. We remember that it is possible to share the new cockpit with other users clicking on the dedicated icon. You can also choose in which folder, among the ones visible to your role, to place your shared document. + + + Multisheet functionality + ---------------------------- + + Cockpit allows to manage data visualization splitting it in two or more sheets. In each layer the user can find and employ the features shown above. Indeed, it is possible to perform a new analysis (as highlighted in Figure below) selecting different datasets and gadgets. + + .. figure:: media/image207_bis.png + + Multisheet cockpit example. + + A user can take advantage of the “move widget” functionality we saw in My first Cockpit to bring widget from one sheet to another. + + Furthermore it is possible, but not mandatory, to set associations between datasets underlying different sheets. The multisheet functionality is particularly useful to focus the analysis in a single spot and have a general overview over it in few clicks at the same time. + + + Export cockpit + ------------------ + + Cockpit document allows to export data into csv file without executing document. This is very useful when you produce data using a heavy query. This option is available if your document has parameters. When you start execution of your document, you will get opened filter panel so you can fill values. To start export, you should click on drop down menu, next to execute button, as on image below. + + .. figure:: media/exportCockpitDrop.png + + Export cockpit into csv. + + After process is finished, you will get notification on **download** icon |download| and you can find your file in **Download manager** section. + + .. |download| image:: media/download.png + :width: 20 + + Clicking on download icon, **Download manager** will open, and you will be able to download zip file that contains csv file/files, depends of how many widgets (chart or table) you have in your document. + + .. figure:: media/downloadManager.png + + Download manager section. diff --git a/functionalities-guide/data-preparation/index.es.rst b/functionalities-guide/data-preparation/index.es.rst new file mode 100644 index 00000000..c7229669 --- /dev/null +++ b/functionalities-guide/data-preparation/index.es.rst @@ -0,0 +1,252 @@ +# Preparación de datos + +## ¿Para qué sirve eso? + +**Preparación de datos** es una funcionalidad disponible desde la versión 8.1 que permite a los usuarios crear un conjunto de datos preparado, a partir de uno existente. +De esta manera, los usuarios pueden crear un conjunto de datos preparado y luego usarlo dentro de un panel o simplemente usarlo como otro conjunto de datos. +Los usuarios tienen la capacidad de crear conjuntos de datos complejos y específicos con bastante facilidad y rapidez, con el fin de utilizarlos para cualquier propósito. + +## Preparación de un conjunto de datos + +El primer paso es seleccionar un conjunto de datos para trabajar. +Puede hacerlo seleccionando el conjunto de datos deseado en la sección de su espacio de trabajo (también debe haber un **Preparación de datos** entrada): + +.. figura:: media/image1.png + + The Data Preparation entry. + +Hay dos formas de preparar e iniciar un proceso de preparación de datos. +El primero es a partir de la sección MyData. +Haga clic en MyData y seleccione el conjunto de datos que desee. + +.. figura:: media/image2.png + + Search for your dataset example. + +Luego haga clic con el botón derecho del mouse y seleccione "Preparación de datos abiertos": + +.. figura:: media/image5.png + + Select "Open Data Preparation" + +Esta operación desencadena el proceso de creación de avro-file. + +.. figura:: media/image6.png + + For more info about what "Preparing avro file" means please refer to "Data Preparation technical detail" section. + +La segunda forma es hacer clic en + botton en la parte superior derecha de la sección Preparación de datos: + +.. figura:: media/image3.png + + Click on + botton on the top right of the page. + +Y luego seleccione su conjunto de datos de origen. + +.. figura:: media/image4.png + + Search for your dataset example. + +Si el archivo avro se crea ahora, debería poder abrir la pantalla de preparación de datos, debería haber un icono de verificación junto al menú de acciones: + +.. figura:: media/image7.png + + There is a check icon on the left icons menu for your selected dataset. + +Pantalla principal de preparación de datos: + +.. figura:: media/image8.png + + Data Preparation main screen. + +## Transformaciones de preparación de datos + +Puede aplicar transformaciones al dataset de origen simplemente eligiendo la acción de transformación, paso a paso, hasta que alcance el resultado deseado. + +En el menú de la barra de herramientas principal, hay un conjunto de transformaciones principales (la mayoría de ellas se pueden aplicar en muchas columnas al mismo tiempo): + +.. figura:: media/image33.png + + Transformations toolbar icons. + +* **Agregar columna**: agrega una nueva columna como campo calculado. +* **Combinar columnas**: agrega una nueva columna que combina dos seleccionadas. +* **Dividir columnas**: Agrega dos columnas dividiendo una seleccionada. +* **Filtro**: Filtra una columna seleccionada por condiciones matemáticas (más información más adelante). +* **Relleno**: agrega caracteres en el lado izquierdo o derecho de una columna seleccionada. +* **Eliminar duplicados**: elimina duplicados de las columnas seleccionadas. +* **Eliminar null**: quita los valores nulos de las columnas seleccionadas. +* **Reemplazar**: Reemplace los valores seleccionados de columnas específicas. +* **Recortar**: elimina los espacios en blanco de columnas específicas. (Disponible solo para una sola columna) +* **Soltar**: Elimine una columna específica. (Disponible solo para una sola columna) + +El **Agregar columna** La transformación permite al usuario agregar un **campo calculado** de tipo numérico, string o temporal. +Estas funciones son un subconjunto de las funciones del lenguaje Spark SQL y se utilizan para cálculos o manipulación de datos. +Para obtener más información, consulte https://spark.apache.org/docs/2.4.8/api/sql/index.html. + +.. figura:: media/image9.png + + Available functions are a subset of Spark SQL language functions + +**Combinar columnas**: agrega una nueva columna que combina dos seleccionadas mediante un separador. + +.. figura:: media/image10.png + + Merge columns dialog example. + +**Dividir columnas**: Crea dos nuevas columnas dividiendo una seleccionada utilizando una condición específica (es decir, un carácter). + +.. figura:: media/image11.png + + Split columns dialog example. + +**Filtro**: Filtra una columna seleccionada por condiciones especiales. + +.. figura:: media/image12.png + +.. figura:: media/image12a.png + +.. figura:: media/image12b.png + + Filter dialog example. + +**Relleno**: agrega caracteres en el lado izquierdo o derecho de una columna seleccionada. + +.. figura:: media/image13.png + + Padding dialog example. + +**Eliminar duplicados**: elimina duplicados de las columnas seleccionadas. + +.. figura:: media/image14.png + + Remove duplicates dialog example. + +**Eliminar null**: quita los valores nulos de las columnas seleccionadas. + +.. figura:: media/image15.png + + Remove null dialog example. + +**Reemplazar**: Reemplace los valores seleccionados de columnas específicas. El carbón viejo es el valor antiguo que se reemplazará. + +.. figura:: media/image16.png + + Replace dialog example. + +Dos transformaciones más están presentes solo haciendo clic en una columna específica: **RECORTAR** y **SOLTAR** Transformaciones. + +.. figura:: media/image17.png + +**Columna de caída**: quita una columna específica de la tabla. + +.. figura:: media/image18.png + + Drop columns dialog warning. + +**Columna de recorte**: Quita los espacios en blanco de la columna. + +.. figura:: media/image19.png + + Trim column dialog example. + +## Detalle técnico de preparación de datos + +**¿Qué es un archivo AVRO?** + +Avro es un sistema de serialización de datos. + +Avro es un marco de serialización de datos desarrollado dentro del proyecto Hadoop de Apache. Utiliza JSON para definir tipos de datos y protocolos, y serializa los datos en un formato binario compacto. + +Avro se basa en esquemas. Cuando se leen los datos de Avro, el esquema utilizado al escribirlos siempre está presente. Esto permite que cada dato se escriba sin gastos generales por valor, lo que hace que la serialización sea rápida y pequeña. Esto también facilita el uso con lenguajes de scripting dinámicos, ya que los datos, junto con su esquema, son completamente autodescriptivos. + +Cuando los datos de Avro se almacenan en un archivo, su esquema se almacena con él, de modo que los archivos pueden ser procesados más tarde por cualquier programa. Si el programa que lee los datos espera un esquema diferente, esto se puede resolver fácilmente, ya que ambos esquemas están presentes. + +Consulte la documentación oficial para obtener más información: https://avro.apache.org/ + +Avro se utiliza para almacenar datos y esquemas de conjuntos de datos de Knowage (con metadatos de columnas) con el fin de utilizarlos como fuente de entrada para el proceso de preparación de datos. + +Cuando el usuario abre un conjunto de datos para la preparación de datos por primera vez, se crea un archivo ad avro. +Este archivo se lee y luego se utilizará como fuente de datos para las transformaciones de datos que se enviarán a Livy-Spark. + +## Guardar y usar un conjunto de datos preparado + +Ahora veamos cómo guardar un conjunto de datos preparado. Para nuestro ejemplo de documentación utilizamos dos transformaciones: DROP y luego un FILTER en la columna "edad". + +Eliminamos la columna "golden_members": + +.. figura:: media/image23.png + + Drop columns dialog example. + +Y luego filtramos por edad menor de 60 años: + +.. figura:: media/image21.png + + Filter columns dialog example. + +La cadena de transformaciones resultante se puede ver a la derecha de la página: + +.. figura:: media/image22.png + + Transformations list is present on the right panel. + +Como puede ver, puede eliminar o obtener una vista previa de la última operación (en nuestro caso la transformación FILTER). + +Para ver una descripción de la transformación, simplemente haga clic en el icono del ojo (si está presente, algunas transformaciones no lo necesitan): + +.. figura:: media/image24.png + + Transformation preview dialog example. + +Puede ver cómo se ha configurado la transformación. +Luego también puede eliminar la transformación haciendo clic en la papelera: + +.. figura:: media/image25.png + + You can delete the last one only. + +Si desea guardar el conjunto de datos preparado, haga clic en el icono de guardar en la parte superior derecha de la página: + +.. figura:: media/image26.png + + Save panel example. + +Aquí puede elegir el nombre, la descripción y la programación si desea actualizar el conjunto de datos, utilizando la transformación seleccionada, periódicamente. + +.. figura:: media/image27.png + + Split columns dialog example. + +Después de hacer clic en el botón GUARDAR, verá un mensaje de confirmación: + +.. figura:: media/image28.png + + Saving confirmation. + +Después de eso, esperando unos momentos, podrá ver sus datos guardados en la fuente de datos seleccionada haciendo clic en el icono del ojo a la derecha en la sección de preparación de datos. + +.. figura:: media/image29.png + + Prepared data preview panel. + +Si la operación de ingesta aún no ha finalizado o si hubo problemas para guardar datos, verá un mensaje de advertencia que indica que la operación no se ha completado. + +Puede monitorear el proceso usando la sección de monitoreo, haga clic derecho en su conjunto de datos preparado guardado y haga clic en "Monitoreo": + +.. figura:: media/image30.png + + Select monitoring entry. + +Verá una ventana emergente con los resultados del proceso, en caso de errores puede descargar un archivo de registro. +En el lado izquierdo también puede cambiar la programación de la actualización periódica del conjunto de datos preparado. + +.. figura:: media/image31.png + + Schedulations and monitoring panel example. + +Ahora es posible ver el conjunto de datos preparado en la sección Administración de conjuntos de datos o en la sección MyData Workpace, por lo que, por ejemplo, puede usarlo más adelante para un panel. + +.. figura:: media/image32.png + + Dataset Management panel example. diff --git a/functionalities-guide/datamining/index.es.rst b/functionalities-guide/datamining/index.es.rst new file mode 100644 index 00000000..5b363444 --- /dev/null +++ b/functionalities-guide/datamining/index.es.rst @@ -0,0 +1,224 @@ +# Minería de datos + +Knowage admite el análisis avanzado de datos, lo que le permite extraer conocimiento de grandes volúmenes de datos, para mejorar su toma de decisiones y estrategias comerciales. En particular, Knowage **Motor de minería de datos** integra las capacidades de scripting de Python. + +Gracias a Knowage **Motor de minería de datos**, es posible ejecutar scripts de Python de forma interactiva y enriquecer los conjuntos de datos tradicionales con nueva información. Esto significa que permite a los usuarios realizar análisis estadísticos o de minería de datos en diferentes conjuntos de datos de Knowage. + +Los científicos de datos pueden integrar su propio algoritmo dentro de Knowage y entregar su resultado al usuario final, junto con nuevas opciones de visualización avanzadas útiles para descubrir información significativa oculta en los datos. + +## Catálogo de funciones + +La minería de datos se puede gestionar a través de la **Funciones** Marco de referencia. En esta sección veremos cómo explorar y manejar esta parte, mientras que en *Usar una función dentro de los documentos* veremos cómo usar las funciones. + +Primero haga clic en el botón **Catálogo de funciones** de la página principal de Knowage como se muestra a continuación. + +.. figura:: medios/menu_catalogo.png + + Functions Catalog from Knowage menu. + +Ingresará a una página como la que se muestra en la figura a continuación. + +.. \_functioncatalinterf: +.. figura:: medios/interfaccia_catalogo.png + +Interfaz de catálogo de funciones. + +Las acciones que un usuario puede realizar dependen del rol del usuario. Sin embargo, independientemente del rol del usuario, una vez introducida la característica todas las funciones se muestran de forma predeterminada. Refiriéndose a la figura anterior, uno tiene la página compuesta por: + +* **Categorías**: estos son establecidos por un usuario administrador y se utilizan para clasificar las funciones de acuerdo con su definición y objetivos. Además, son de ayuda para navegar por las funciones; solo el usuario administrador puede agregar y/o modificar categorías. + +* **Etiquetas**: se utilizan para agudizar fácilmente la investigación y recordar fácilmente las funciones que se etiquetan con esa palabra; una vez más, solo el usuario administrador puede agregar y/o modificar etiquetas; + +* **Lista de funciones** (si los hay): estos son visibles y explorables por cualquier tipo de usuario. De todos modos, solo un usuario administrador puede agregarlos y / o modificarlos. + +.. indirecta:: +**Agregar o modificar las categorías** + + The admin can add a new category using the Domain management available on Knowage Server under the Server Settings section. To know more about this section, please refer to Section “Server settings” of the General Administration Manual. + +Las categorías de funciones dependen de un usuario administrador. Toma *Interfaz de catálogo de funciones* Figura a modo de ejemplo, tenemos: + +1. **Análisis de texto**: dar sentido al texto no estructurado, + +2. **Aprendizaje automático**: enseñe a su aplicación a enseñarse a sí mismo, + +3. **Visión por computador**: identificar objetos en imágenes, + +4. **Utilidades**: microservicios listos para usar, + +5. **Todo**: visualiza todas sus funciones; esta es la única categoría que no se puede cambiar ni eliminar. + +Para facilitar la comprensión creamos algunas funciones para ser examinadas. Recordamos aquí que uno puede buscar una función de diferentes maneras: usando las categorías o las etiquetas o usando el cuadro "Buscar" del Catálogo de funciones disponible en la parte superior de la lista de funciones como se destaca a continuación. + +.. figura:: media/image398.png + + Search box to look for a function. + +Suponemos aquí seleccionar una categoría, lo que significa hacer clic en el cuadro de categoría, para poder analizar las funciones que pertenecen a ella. + +Tenga en cuenta que la parte subrayada de la figura siguiente contiene una lista de etiquetas. Estos ayudan a centrarse en los temas y, por lo tanto, en las funciones asociadas a esa categoría. Viceversa, cuando se muestran todas las funciones, también se muestran todas las etiquetas y se pueden usar para recoger funciones relacionadas con ese tema. + +.. figura:: media/image399400.png + + Using tags and categories to look for functions. + +Se puede ejecutar una vista previa de la función utilizando el icono |image417| que abre un cuadro de diálogo en el que puede seleccionar y configurar un conjunto de datos entre los disponibles para probar la función. Utilice el icono |image4172| para eliminar la función. Las funciones no se pueden eliminar si se utilizan dentro de uno o más documentos. + +.. |imagen417| imagen:: media/image401.png +:ancho: 30 + +.. |imagen4171| imagen:: media/image402.png +:ancho: 30 + +.. |imagen4172| imagen:: media/image403.png +:ancho: 30 + +Para crear una nueva función, un usuario administrador debe hacer clic en el icono "Más" disponible en la esquina superior derecha de la página. La acción abre la interfaz que se muestra a continuación. Aquí tienes cuatro pestañas que describimos brevemente en las siguientes subsecciones. + +.. \_creatingnewfunct: +.. figura:: media/image404.png + + Creating a new function. + +La ficha General + +``` + +In this tab the user gives the general information about the function as the figure above shows. The admin user must type: the *name* of the function, the *label* with which it is identified uniquely (remember to use only numbers or letters and do not leave spaces between them). The *keywords* are were tags are defined. The *Description* is where the user can insert a text or images to be shown when the function is being configured inside documents. In the *Benchmarks* field users can insert information about the function performances. + +The Input tab +~~~~~~~~~~~~~~~ + +As shown in the following figure, the function admits two kinds of input: *columns* and *variables*. + +.. figure:: media/function_input_tab.png + + Input tab. + +In the “Column” instance the function takes input columns that will be referenced inside the script. These columns are generic, the user must only specify their type and the name he later wants to use inside the script to access that specific column. + +.. figure:: media/function_input_tab_column.png + + The dataset input of the function settings. + +In the “Variable” case, the user must insert one or more variables and match them with values using the dedicated area. + +.. figure:: media/function_input_tab_variable.png + + The variable input of the function settings. + +The Script tab +~~~~~~~~~~~~~~~~ + +The script tab is where an expert user defines the function through the usage of datamining languages (such as Python), as shown in Figure below. + +.. figure:: media/function_script_tab.png + + The script tab. + +Inside the script users will have at their disposal a read-only `pandas.Series `__ variable for each column defined in the input tab. +To reference one specific column users must use the placeholder *${column_name}*. Input variables will be accessible with the same syntax. + +.. code-block:: bash + :caption: Code syntax to recall inputs + :linenos: + + ${column_name} + ${variable_name} + +.. warning:: + **Input variables are read only** + + If you want to manipulate them you should first make a local copy and work on it. + +The script will have to produce as output one or more *pandas.Series* variables, and will store them inside the corresponding output placeholders. The following is an example of function template. + +.. figure:: media/catalog_function_example_script.png + + Function template example. + +The Output tab +~~~~~~~~~~~~~~~~ + +Finally it is important to define what kind of outputs the function has produced, according to the script generated in the previous tab. Using the “Output“ tab shown below, you must specify: + +.. figure:: media/function_output_tab.png + + Output tab. + +- **Field Type**: it can be *ATTRIBUTE* or *MEASURE*, and defines how the column will behave inside documents; +- **Type**: it depends on the selected Field Type, it can be *String*, *Number (float)* or *Date*; + + +Engine description +-------------------------- + +The Catalog Function features leverage on the Python Engine. To understand how to install and configure it, please refer to the `Installation Manual `__ + +Use a function inside documents +-------------------------------------------------- + +Now that functions have been created, they must be used inside documents. In this section we will go through all the steps that allow users to execute a function with a specific dataset. +This works both for the function preview and for the function used inside cockpits. +Depending on the scenario, you will have two different dialogs. +When you are previewing the output of a function, you need to select the dataset you want to use to perform the preview. Therefore on the left card you will be able to select a dataset among the available ones. If the dataset has parameters you will be asked to insert values. + +.. figure:: media/catalog_function_preview_interface.png + + Preview interface. + +Instead, when you are creating a new widget that uses a function, you will need to click on the *Use function button* to access the configurator. + +.. figure:: media/catalog_function_usefunction_widget.png + + Use a function in a widget. + +.. warning:: + **You cannot use more than one function in the same widget** + + If you try do so you will get an exception. + +.. note:: + **Functions are available only in some widgets** + + Table, crosstable and custom chart. + +If you are using a function inside a widget it means that you have already selected the dataset you want to use. Therefore on the left card you will be able to select a function among the available ones. + +.. figure:: media/catalog_function_widget_interface.png + + Catalog function interface in widgets. + +From this point forward the rest of the configuration is identical for both widget and preview. The first thing that you have to do on the right tab, is bind the input columns of the function with the actual columns coming from the chosen dataset. +By doing this you are providing the **actual data** to the function template. From time to time you can provide different data to the same function just by changing the selected dataset. Depending on this, the same algorithm that is saved inside the function template will work on a different set of data and return different outputs. + +.. figure:: media/function_input_column_binding.png + + Input columns binding. + +If you have defined some input variables, you can also set their values. + +.. figure:: media/function_input_variables_binding.png + + Input variables binding. + +The last thing you have to choose is the working environment. You can choose the environment among the available ones. To understand better what is an environment, please refer to the `Installation Manual `__ + +.. figure:: media/function_environment_binding.png + + Choose the working environment. + +After choosing an environment, the list of available libraries installed inside that specific environment appears on screen. You can search or filter libraries and their version in order to find the desired ones, and based on this you can choose the environment that suits your needs the most. + +.. figure:: media/function_new_columns.png + + New columns generated by the functions. + +After saving if you are inside widget configuration you will see that the new output columns generated by the function have been added to the dataset as shown in the figure above. +Instead if you were running a preview you will see the output of the dataset execution appearing on screen as shown in the figure below. + +.. figure:: media/function_preview_output.png + + Output of the function preview. + +``` diff --git a/functionalities-guide/dataset-preview/index.es.rst b/functionalities-guide/dataset-preview/index.es.rst new file mode 100644 index 00000000..7cb004a8 --- /dev/null +++ b/functionalities-guide/dataset-preview/index.es.rst @@ -0,0 +1,63 @@ +# Vista previa del conjunto de datos + +El **vista previa del conjunto de datos** es una funcionalidad presente en el espacio de trabajo, en la cabina y en el informe BIRT que logrará obtener una vista previa del conjunto de datos y el parámetro seleccionados. + +## Estructura de vista previa del conjunto de datos + +.. figura:: media/image01.png + + Dataset preview example screenshot. + +Como puede ver en el ejemplo, en la vista previa del conjunto de datos puede ver las columnas del conjunto de datos resaltadas con diferentes colores +dependiendo del tipo de datos. Las mismas columnas de tipo de datos compartirán el mismo color. + +Para cada columna, podrá leer el nombre de la columna y el tipo de columna dentro del encabezado de la columna. +En la parte inferior aparecerá una paginación si es necesario. + +Para algún conjunto de datos específico, la barra de exportación también estará disponible. Si el conjunto de datos seleccionado admite esta funcionalidad +aparecerá una barra en la parte superior del cuadro de diálogo. Al hacer clic en los botones dentro, podrá descargar la vista previa en el +formato seleccionado. + +.. figura:: media/image02.png + + Dataset export bar. + +## Exportación de vista previa del conjunto de datos + +Al hacer clic en el botón de exportación, o si el valor predeterminado para esa vista previa está configurado para descargarse, se realiza un proceso de exportación +comenzará en segundo plano. + +Una vez finalizado el proceso, aparecerá una insignia de notificación en el *Descargas* icono de menú. + +.. figura:: media/image02b.png + + Download notification badge. + +## Dentro del espacio de trabajo + +Dentro del espacio de trabajo, puede acceder a la vista previa del conjunto de datos haciendo clic en el botón de vista previa como en el ejemplo a continuación. + +.. figura:: media/image03.png + + How to access workspace preview. + +## Cabina interior + +Dentro de la cabina, puede encontrar la configuración de vista previa del conjunto de datos en la siguiente configuración de widgets: +\- Widget de tabla +\- Widget de gráfico +\- Widget html + +Al abrir la configuración del widget, el botón *cruz* estará disponible, con las funcionalidades de navegación cruzada y vista previa. + +.. figura:: media/image04.png + + Preview navigation configuration. + +Al habilitar el interruptor de vista previa, tendrá la posibilidad de elegir qué conjunto de datos se mostrará en la vista previa. + +Si se establecen algunos parámetros del conjunto de datos, estos serán visibles en la lista siguiente. +Es posible establecer el valor del parámetro de diferentes maneras dependiendo del widget seleccionado. + +Seleccionar *Descarga directa* permitirá al usuario exportar directamente el resultado de la vista previa en la interacción. +La descarga estará disponible como una exportación de vista previa común dentro del menú de descargas. diff --git a/functionalities-guide/dossier/index.es.rst b/functionalities-guide/dossier/index.es.rst new file mode 100644 index 00000000..1ec96807 --- /dev/null +++ b/functionalities-guide/dossier/index.es.rst @@ -0,0 +1,177 @@ +# Expediente + +Un documento de dossier le permite obtener un archivo procesado a partir de una plantilla de entrada. Un ejemplo típico de uso de esta característica es la creación de un archivo con contenido variable actualizado en cada ejecución. Para ello, debe crear un documento de dossier con una plantilla XML bien configurada. + +.. importante:: +**Edición Enterprise** + + If you purchased Knowage EE, the following features are available only in KnowageER license. + +## Plantilla XML + +Etiquetas y propiedades + +``` + +XML template is an XML file used to configure parameters needed to the elaboration. This file is uploaded during document creation and can be updated using the HISTORY tab visible in document edit mode. + +In particular, tag allowed are: + +- **DOSSIER**: main tag used to define the dossier template; +- **PPT_TEMPLATE**: contains properties related to the PPT template (incompatible with DOC_TEMPLATE). You can specify: + + - *name*: the name of the template file name (Supported file types are PPT, PPTX); + +- **DOC_TEMPLATE**: contains properties related to the DOC template (incompatible with PPT_TEMPLATE). You can specify: + + - *name*: the name of the template file name (Supported file types are DOCX); + - *downloadable*: true/false. Enable/disable the download of the template (optional); + - *uploadable*: true/false. Enable/disable the upload of the template (optional); + +- **REPORT**: contains document's properties. You can specify: + + - *label*: the label of the document to be executed; + - *imageName*: the name of the image inside the docx document. If the document is multisheet, imageName value will be composed by the document label ending with the suffix "_sheet_". For example, to use the screenshot of the first sheet, the value will be "documentLabel_sheet_0". This name can be set into title or description using the alternative text menu of the picture; + - *sheetWidth*: the value of the width of the sheet (in pixels). This value will be used if sheetHeight is also set (optional); + - *sheetHeight*: the value of the height of the sheet (in pixels). This value will be used if sheetWidth is also set (optional); + - *deviceScaleFactor*: the value to use as the scaling factor to be applied when capturing the screenshot (optional); + +- **REPORTS**: encloses all REPORT tags; +- **PARAMETER**: sets parameter for the document's execution. You can specify: + + - *type*: static/dynamic. Defines the type of the analytical driver. It must be the same as the one of the document to be executed; + - *url_name*: the url name of the analytical driver to be used. It must be the same as the one of the document to be executed; + - *url_name_description*: the description displayed in the driver value input panel for the analytical driver; + - *dossier_url_name*: the url name of the analytical driver set into detail mode; + - *value*: the value to be set into the driver (mandatory if type="static"); + +- **PARAMETERS**: encloses all PARAMETER tags; +- **PLACEHOLDER**: sets the placeholder. You can specify: + + - *value*: the text to be replaced; + +- **PLACEHOLDERS**: encloses all PLACEHOLDER tags. + +.. warning:: + + This feature is compatible with docx created with Microsoft Word 2010 and later. + + +Image adding (PPT_TEMPLATE) +------------------------------ + +Suppose you have to create a ppt/pptx file where to place the images relating to one or more reports. You have only to configure XML template defining some placeholders to be use for replacing and execute it. Below is shown an example of an XML template used for this purpose. + +.. code-block:: xml + :linenos: + :caption: Example (a) of template for Dossier for Image replacement on docx file. + + + + + + + + + + + + + + + + +The example above is using one placeholder and one static analytical driver. + +.. warning:: + + Please note that the file to be used as a template must be placed in ``TOMCAT_HOME/resources//dossier`` path. + + +Image replacing (DOC_TEMPLATE) +-------------------------------- + +Suppose that you have to draw up a document where text is static but images related to need to be updated. + +By this functionality you will be able to use a docx file as a template and replace images inside it. More precisely, you can configure your XML and docx templates to allow Knowage to replace specific images with new ones obtained by the execution of specified documents. + +Below is shown an example of an XML template used for this purpose. + +.. code-block:: xml + :linenos: + :caption: Example (a) of template for Dossier for Image replacement on docx file. + + + + + + + + + + + + + + + + + + + + + + + + + + +Also docx document must be modified to be compatible with the replacer. + +In particular: + +- images in the document must be inserted by copying and pasting from the file system (or using the "insert image" feature); +- each image must have a unique name +- imageName in the XML template must match the title (alt text) of the image in the docx. + +.. warning:: + + To optimize dossier creation procedure, same document will be executed more than one time if and only if its parameters change. In that scenario sheetHeight, sheetWidth and deviceScaleFactor will be set for every execution. Moreover, if parameters don't change, document will be executed only one time and sheetHeight, sheetWidth and deviceScaleFactor values will stay the same as the first execution. + + +My first dossier +---------------- + +You can create a dossier document by using the plus button and choosing "Generic Document". Proceed by filling in the necessary fields, choosing the XML template and selecting "Collaboration" as the type and "Dossier engine" as the engine. If the documents to be executed have one or more analytical drivers, these drivers must be added to the dossier document from the DRIVER tab. + +.. figure:: media/image000.PNG + + Dossier document creation interface. + +After saving the document, you can access the dossier activity page by clicking the play button. + +.. figure:: media/image001.PNG + + Dossier activity interface. + +If one or more dynamic analytic drivers are set, the required inputs must be provided in the sliding menu that appears from the right. You will then go to the dossier activity page. + +.. figure:: media/image002.PNG + + Dossier activity interface. + +If upload/download are enabled, file template can be uploaded/downloaded using the three dot menu on the top right of the "Details" tab. + +.. warning:: + + This feature is available only for image replacing procedure. + + +If you want to execute your document, you must enter a name for the activity and click on "LAUNCH ACTIVITY". A new task will be started in the STARTED state and a new row will be visible in the table below. At the end of the execution of the task, the processed file can be downloaded with the appropriate download icon. + +.. figure:: media/image003.PNG + + Dossier activity execution finished. + +Each line allows you to see useful information on the activity (such as the values of the drivers used for execution) by clicking on the info icon, download the processed file by clicking on the download icon and remove itself by clicking on the trash icon. +``` diff --git a/functionalities-guide/free-inquiry/index.es.rst b/functionalities-guide/free-inquiry/index.es.rst new file mode 100644 index 00000000..635c0df5 --- /dev/null +++ b/functionalities-guide/free-inquiry/index.es.rst @@ -0,0 +1,599 @@ +# Consulta gratuita + +Esta guía de usuario detallada está dedicada al Qbe (acrónimo de Query By Example), un instrumento de consulta gratuita que permite a los usuarios un acceso fácil y gratuito a la información a través de interfaces gráficas. + +Free Inquiry indica el modus operandi de analistas y usuarios operativos que generalmente buscan análisis de negocios que no se limiten a listas de resultados preestablecidas. Este método tiene un nivel medio de dificultad ya que requiere un conocimiento adecuado de la gestión de datos y una organización estructurada del trabajo. + +QbE es la herramienta que te permite desarrollar tu consulta gratuita a través de una modalidad totalmente gráfica. Además, puede ejecutar la consulta, verificar los resultados, exportarlos y guardar la consulta para su uso posterior. + +El material se dividirá en dos secciones principales. El primero está dedicado a construir consultas en el entorno de Knowage Server, suponiendo que un usuario experto ya haya creado un modelo de negocio adecuado para analizar. En la segunda parte, proporcionaremos al usuario los pasos principales para construir un modelo de negocio adecuado a través del diseñador Qbe disponible en Knowage Meta. + +## Mi primera consulta por ejemplo + +**QbE** (es decir, Query By Example) le permite consultar (un subconjunto de) una base de datos a través de una representación de alto nivel de las entidades y relaciones. Sus principales características son: + +* tiene una RICA GUI de usuario final; +* permite seleccionar atributos y establecer filtros; +* no requiere ningún conocimiento de las estructuras de datos; +* requiere un conocimiento semántico de los datos; +* es útil cada vez que la consulta gratuita sobre los datos es más importante que su diseño gráfico; +* deja libre la gestión de los resultados; +* es compatible con las capacidades de exportación; +* permite la ejecución repetible de las investigaciones; +* funciona en un dominio de datos con limitaciones. + +La creación de una consulta QbE no requiere ningún conocimiento técnico, sino conocimiento del dominio de datos: los aspectos técnicos, como la creación de filtros, la agregación y los criterios de ordenación, se gestionan mediante una interfaz gráfica fácil de usar. + +Supongamos que un administrador ha construido un modelo de negocio y, en consecuencia, lo ha lanzado en Knowage Server. Esto permite al usuario acceder al modelo, consultar las entidades disponibles y guardar los resultados como un conjunto de datos, utilizable más adelante en otros documentos de Knowage, como cabinas. + +A continuación discutimos cada paso en detalle, mostrando las funcionalidades básicas y avanzadas de la **QbE Editor**. + +Diseño y ejecución de consultas + +``` + +To open the QbE editor, access the **Models** section, available in the end user's **Workspace**. Then, simply click on the model icon to reach the QbE graphical interface. + +In this paragraph we show how to build a simple query with the QbE editor. + +.. figure:: media/qbeDesigner.png + + QbE editor. + +As shown in Figure 9.1 the window of the QbE editor contains the **Query designer**. In next sections we explain in detail all the areas of the **Query Designer**, the **Datamart Schema** tab, the query editor and a hidden tab dedicated to the management of queries, subqueries and parameters catalogue. + +Datamart Schema +^^^^^^^^^^^^^^^^ + +Starting from the left side: + The upper Panel shows the searchable logical schema and the list of entities that can be queried to generate the query. Entities are represented in a tree structure, with user-defined names. Field can be added in the query (right area) clicking on it. + The lower Panel shows list of created subqueries in a tree structure where children are fields of subquery + +There are few types of entities: *facts*, represented by a cube symbol.(i.e., the Sales entity), *dimensions*, represented by a four-arrows symbol (i.e., the Product entity), *geographical dimension*, represented by *earth* icon. + +Each single entity is composed of a title, some attributes or measures and relationships with other entities. Relations are available clicking on *i* icon of one entity. In particular, by exploding the content of an entity (i.e. Sales as in figure above), you may encounter the following elements: + +- **measure**: it refers to fields associated with numeric data (e.g. UNIT SALES); +- **attribute**: it refers to fields that can be associated to a category (e.g. PRODUCT ID); +- **relation**: it refers to relationships or connections between two entities (e.g. relationship between the sales and the product dimension). + +.. figure:: media/image300.png + + Relations of one entity. + +There are two available views: smart and advanced. When qbe is opened by default user will see smart view. Clicking on one field of one entity that field will be added in the query and results will be displayed without any other user interaction. + +.. figure:: media/smart.png + + Smart view. + +User can switch to advanced view clicking on Smart view in top right corner. User can continue adding fields in the query but without seeing result. + +.. figure:: media/advanceView.png + + Advanced view + + +Let us see more in detail how to add calculated fields. + +Calculated fields management +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +You can create new calculated fields inside a query. In advanced view there will be available option for creating **calculated fields**. Clicking on **Calculator** icon **Calculated field wizard** will open. + +To build a calculated field, you shall define: + +- **Name**; +- **Type**: string, number or date; +- **Nature**: measure or attribute; +- **Formula**: you can click on the fields included on the left and build the formula. + +An example is provided below. + +.. figure:: media/calculateFieldWizard.png + + Calculated field wizard. + + +Query Editor +^^^^^^^^^^^^^^^^ + +Central panel provides a query editor. As we already mentioned, there are two available views: smart and advanced. + +Elements from the datamart schema on the left can be added into the query editor. To remove an field from the query editor, just click on the x icon, or if advanced view is opened, clicking on three dots icon, **Delete field** is available. + +Selected Fields +^^^^^^^^^^^^^^^^ + +Central panel contains the list of columns to be returned by the query. To add a new field in this section, just click on a field in the schema panel tree. + +This panel is structured as a table: columns contain the fields selected from the datamart schema. Every column has **gear icon** on the top (smart view), that is providing applicable functions as shown below, plus icon for deleting field form query and for ordering. + +.. figure:: media/image212.png + + Select fields interface in smart view. + +In the advanced view, every row include applicable functions as shown below, plus clicking on **three dots icon** there are few more functions. + +.. figure:: media/image213.png + + Select fields interface in advanced view. + + +With available functions it is possible to: + +- **Alias**: define aliases for fields: those aliases are shown as column headers in the result table; it is editable +- **Function**: in case of aggregation, define the aggregation function (e.g., **SUM**, **AVERAGE**, …) on the non-grouped items; +- **Order**: define a sorting criteria: double click on the **Order** column to set the ordering criteria; +- **Group**: in case of aggregations, define the attribute that you want to group on (if you know SQL syntax, these attributes are the ones you should place in the GROUP BY clause); +- **Visible**: indicate whether a column shall be visible in the result (hidden attributes are used and returned by the generated query, but are not shown in the result table); +- **In Use**: indicate whether a column shall be used to select the relative one during query execution or just to be used in calculated field +- **Filter**: add a filter criteria: clicking on this filter icon redirects you to the **Filters** tab; + +It is possible to edit alias, clicking on gear icon (smart view) and on **Alias item**. In advanced view, alias can be changed clicking on cell of alias column. + +.. figure:: media/aliasChange.png + + Change alias. + +Pay attention to grouping options: if you want to define an aggregation function on a field (like, for instance, the **COUNT** of the sold items), you shall tick the Group checkbox for all the other fields added in the query editor, without an aggregation function defined, otherwise you will get an SQL exception. The possible grouping functions are shown in the following figure. + +.. figure:: media/image214.png + + Aggregation functions. + +When you drag attributes belonging to entities that are linked through a relationship path, the QbE automatically resolves relationships between attributes (implicit join). + +Moreover, multiple relationships may occur among entities. A typical example concerns dates. Suppose you have two relationships between the **Order** fact table and the **Time** dimension table: the first links the order_date column of the first table to the *time_id* column of the latter, while the second relationship joins the *shipping_date* column to the *time_id column*. + +In this case, when dragging fields from both the **Order** entity and the **Time** entity you may want to specify which relationship will join the two tables: for instance, you may want to know the total number of orders according to the ordering month, the shipping month or for both. In all these situations, you can set the relationship to be used by clicking the **Relationships wizard** button at the top right corner of the panel. A pop up window opens where you can define the path to be used. Please refer to Multiple relationships section for all details regarding the disambiguation of relationships. + +The toolbar about query editor sub-section has a toolbar contains additional functionalities summarized in Table below. + +.. table:: Select fields toolbar options + :widths: auto + + +-----------------------------------+-----------------------------------+ + | Button | Description | + +===================================+===================================+ + | **Join definitions** | Displays relations between | + | | query entities | + +-----------------------------------+-----------------------------------+ + | **SQL** | Shows SQL generated by the | + | | graphical interface | + +-----------------------------------+-----------------------------------+ + | **Discard Repetitions** | Remove duplicated rows from | + | | results, if any | + +-----------------------------------+-----------------------------------+ + | **P** | Add parameters | + | | | + +-----------------------------------+-----------------------------------+ + | **Calculator** | Add calculated fields | + | | | + +-----------------------------------+-----------------------------------+ + | **Three gears** | Open advanced filters panel | + | | | + +-----------------------------------+-----------------------------------+ + | **Eye** | Show/hide hidden fields | + | | | + +-----------------------------------+-----------------------------------+ + | **Smart View** | Switch between smart and | + | | advanced view | + +-----------------------------------+-----------------------------------+ + | **Play** | Preview query | + +-----------------------------------+-----------------------------------+ + | **Three dots** | Option to choose between Deleting | + | | all fields from query and Export | + | | query into csv/xls/xlsx | + +-----------------------------------+-----------------------------------+ + +Filters +^^^^^^^^ + +The **Filters** panel allows you to define filter criteria (WHERE clause). Filters are structured as a table: here rows contain filters, while columns represent the elements of the filter. Filters panel can be opened in three ways: +- In smart view clicking on **Filter icon** on the field in entity +- In smart view clicking on **filter icon** on the already added field in the query +- In advanced view clicking on three dots and **Filters item** + +Adding new filter is possible clicking on **+** icon. + +Removing the filter is possible clicking on **eraser** icon. + +.. figure:: media/addDeleteFilter.png + +Filters are expressions of type: + + **Left operand + Operator + Right operand.** + +Structure of Filters panel is: + +- the **Field, Condition, Target** columns allow you to define filters according to the syntax defined above. +- the **Target type** column define the types of right operand: manual, value of the field, another entity, parameter, subquery; + +With target type **manual** you should fill input **target** with value that you want to be right operand. + +.. figure:: media/manualTarget.png + + Manual target type + +With target type **value of the field** lookup function is activated to facilitate selection of values. You are able to choose values for right operand. If you are choosing two values, you should set condition to be **between**, **not between**, **in** or **not in**. If you are choosing more then two values, you should set condition to be **in** or **not in**. + +.. figure:: media/lookupFunction.png + + Filter lookup for right operand selection. + +With target type **another entity** you will get option to choose field from another entity for your right operand. + +.. figure:: media/anotherEntity.png + +About target type **subquery** and **parameter** there will be more words later. + + +.. important:: + **Enterprise Edition only** + + Filtering data with fields type of date/time/timestamp using calendar/time/calendar is available only for Enterprise Edition. + +If you have SI license file, you will get the chance to filter your data with fields type of date/time/timestamp using calendar/time/calendar + time option. This depends of what is data type of you field, and this is coming form metamodel creation phase. +When creating your metamodel, you can set data type of to your field. + +.. figure:: media/timeDataType.png + + Metamodel creation. + +.. figure:: media/date.png + + Filters creation on date data type of the field. + +.. figure:: media/time.png + + Filters creation on time data type of the field. + +.. figure:: media/timestamp.png + + Metamodel creation, timestamp data type of the field. + +Note that more complex combinations of filters can be defined using the advanced filter wizard, which you ca find selecting the **Three gears** icon. + +In the following table the possible types of filters in the QbE are summarized. The use of subqueries in filters is explained later in *Advanced QbE functionalities* paragraph. + +.. table:: Possible combinations of filters in the QbE. + :widths: auto + + +-------------+-------------+-------------+-------------+-------------+ + | Filter type | Left | Operator | Right | Example | + | | operand | | operand | | + +=============+=============+=============+=============+=============+ + | Basic | Entity.attr | Any | value | Prod.family | + | | ibute | | | = | + | | | | | | + | | | | | 'Food' | + +-------------+-------------+-------------+-------------+-------------+ + | Basic | Entity.attr | Any | Entity.attr | Sales.sales | + | | ibute | | ibute | > | + | | | | | Sales.cost | + +-------------+-------------+-------------+-------------+-------------+ + | Parametric | Entity.attr | Any | [parameter] | Prod.family | + | | ibute | | | = | + | | | | | | + | | | | | [p_family] | + +-------------+-------------+-------------+-------------+-------------+ + | Dynamic | Entity.attr | Any | prompt | Prod.family | + | | ibute | | | = ? | + +-------------+-------------+-------------+-------------+-------------+ + | Value | Entity.attr | In | subquery | Sales.custo | + | list | ibute | | | mer | + | from | | /not in | | in subquery | + | subquery | | | | | + +-------------+-------------+-------------+-------------+-------------+ + | Single | subquery | < = > | value | Subquery > | + | value | | | | 0 | + | from | | | | | + | subquery | | | | | + +-------------+-------------+-------------+-------------+-------------+ + +When filtering a date attribute or a time attribute it is possible to apply a timespan to ease the insertion of values. Following the images below, we can see that the Timespan button appears when filterting, for instance, a date attribute. We recall that is it possible to configure a new timespan using the dedicated Knowage functionality we described in the administrator guide. + +.. figure:: media/imageTS005.png + + Filtering date attribute: use a timespan. + +After selecting one timespan, the user must clcik on apply to ask the server to insert the start and end values. + +.. figure:: media/imageTS006.png + + Filtering date attribute: apply a timespan. + +Finally click on the save button and data is filtered accordingly. + + +Query Preview +^^^^^^^^^^^^^^^ + +While you are in smart view you can see preview of you query. +While you are in advanced view, and you are satisfied with your query or if you want to check the results, you can see the returned data by clicking the **Play** button located in the top right corner of the panel. From there, you can go back to the **Designer** to modify the definition of the query. + +.. figure:: media/preview.png + + Preview wizard. + +In case you have started the QbE editor directly from a model (that is, you have clicked on a model icon in the **My Data** > **Models** section) from here you can also click the **Save** button located in the top right corner of the page to save your query as a new dataset, reachable later from the **My Data**> **Dataset** section. Please note that this operation saves the *definition* of your query and not the snapshot of the resulting data. This means that every time you re-execute the saved dataset, a query on the database is performed to recover the updated data. + +We highlight that when the save button is selected, a pop up shows asking you to fill in the details, split in three tabs: + +- **Generic**, in this tab you set basic information for your dataset like its **Label**, **Name**, **Description** and **Scope**. +- **Persistence**, you have the chance to persist your dataset, i.e., to write it on the default database. Making a dataset persistent may be useful in case dataset calculation takes a considerable amount of time. Instead of recalculating the dataset each time the documents using it are executed, the dataset is calculated once and then retrieved from a table to improve performance. You can also decide to schedule the persistence operation: this means that the data stored will be update according to the frequency defined in the **scheduling** options. + +Choose your scheduling option and save the dataset. Now the table where your data are stored will be persisted according to the settings provided. + +- **Metadata** It recaps the metadata associated to the fields involved in your query. + +.. figure:: media/saveQbeDS.png + + Save qbe dataset. + + +Advanced QbE functionalities +``` + +En esta sección nos centramos en las funciones avanzadas, que pueden ser gestionadas cómodamente por usuarios más expertos. + +Uso de campos espaciales +^^^^^^^^^^^^^^^^^^^^^^^ + +.. importante:: +**Solo Enterprise Edition** + + Spatial dimension is available only for Enterprise Edition with LI licence. + +El motor Qbe admite consultas espaciales a través de un conjunto de operadores (que devuelven true o false) o un conjunto de funciones (estas generalmente devuelven una medida). Aunque esta característica solo está disponible cuando se posee la licencia de Location Intelligence (LI) y cuando los datos se almacenan en la base de datos Oracle 12c. También es fundamental que el Modelo de Negocio tenga que ser etiquetado como modelo geográfico. Puede consultar la sección Meta Web para obtener detalles sobre cómo establecer la opción geográfica utilizando Knowage Meta. + +Suponemos que tenemos un BM con dimensiones geográficas habilitadas (por un usuario técnico). En este caso, las dimensiones que tienen campos espaciales están marcadas con el icono de la brújula |earthIcon|. Una vez expandida la dimensión espacial, se enumeran los campos. Aquí no hay un símbolo de seguimiento para distinguir entre los atributos geográficos y el "normal". Por ello es muy importante que el usuario esté previamente informado de qué campos tiene propiedades geométricas. + +.. |Tierraico| imagen:: media/earthIcon.png +:ancho: 30 + +.. figura:: media/image218.png + + QbE spatial dimensions. + +Después de una primera selección de campos, es posible agregar campos calculados. Haga clic en el botón **Calculadora** opción disponible en el área del editor de consultas como se muestra en la flecha azul de la figura siguiente. Tenga en cuenta que se abre un asistente: puede utilizar este editor para insertar un nuevo campo obtenido a través de una secuencia finita de operación en los campos seleccionados. Los círculos de la siguiente figura subrayan que los campos sobre los que se puede operar son los previamente seleccionados con un simple clic en el campo. + +.. \_calculfldwizardspt: +.. figura:: media/image219.png + + Calculated field wizard with spatial filters. + +Además, tenga en cuenta que el **Artículos** panel proporciona todas las funciones aplicables ordenadas por categorías: + +* funciones de agregación, +* funciones de cadena +* funciones de tiempo, +* funciones espaciales, +* funciones sql, +* función personalizada (si están registrados). + +.. advertencia:: +**Tener en cuenta la definición de la función Oracle** + + It is important to refer to Oracle Documentation to know the arguments, in terms of type and number, of each function to assure the right functioning and do not occur in errors while running the Qbe document. + +Estos últimos están disponibles solo en presencia de un modelo de negocio geográfico y *mosto* aplicarse correctamente a atributos o medidas espaciales. La siguiente figura muestra la lista de las funciones espaciales disponibles, mientras que la siguiente tabla le ayuda a usarlas correctamente, proporcionando el nombre de la función Oracle correspondiente y un enlace para obtener información más específica sobre el uso, el número de argumentos, el tipo y la salida. + +.. figura:: media/image220.png + + Spatial function list. + +.. \_linkoraclesptfnct: +.. table:: Enlace a funciones espaciales de Oracle. +:widths: automático + + +-----------------------+-----------------------+ + | Function Name | Oracle Function | + +=======================+=======================+ + | **distance** | SDO_GEOM.SDO_DISTANCE | + +-----------------------+-----------------------+ + | **dimension** | GET_DIMS | + +-----------------------+-----------------------+ + | **centroid** | SDO_GEOM.SDO_CENTROID | + +-----------------------+-----------------------+ + | **geometrytype** | GET_GTYPE | + +-----------------------+-----------------------+ + | **length_spa** | SDO_GEOM.SDO_LENGTH | + +-----------------------+-----------------------+ + | **relate** | SDO_GEOM.RELATE | + +-----------------------+-----------------------+ + | **intersection** | SDO_GEOM.INTERSECTION | + +-----------------------+-----------------------+ + +Para aplicar una función, haga clic en el nombre de la función y se abrirá el asistente "Ventana de selección de operandos". La siguiente figura muestra un ejemplo para la función "Distancia". Rellene todas las casillas ya que todos los campos son obligatorios. + +.. figura:: media/image221.png + + Operands selection window. + +Finalmente, puede usar la función espacial para agregar un campo calculado, como se muestra a continuación. + +.. figura:: media/image222.png + + Example of added calculated field using a spatial function. + +Además de los campos calculados, es posible filtrar en campos espaciales utilizando operadores geométricos específicos. Una vez más informamos en la Figura a continuación del operador geométrico disponible (puede encontrarlos desplazándose por el panel hasta la parte inferior) e informamos el enlace a las páginas web de Oracle en la siguiente tabla. + +.. figura:: media/image223.png + + Spatial filters. + +Vea la siguiente tabla: + +.. \_linkoraclefltrfnct: +.. table:: Enlace a las funciones de filtro de Oracle. +:widths: automático + + +-----------------------+-----------------------+ + | Function Name | Oracle Function | + +=======================+=======================+ + | **touches** | SDO_TOUCH | + +-----------------------+-----------------------+ + | **filter** | SDO_FILTER | + +-----------------------+-----------------------+ + | **contains** | SDO_CONTAINS | + +-----------------------+-----------------------+ + | **covered by** | SDO_COVEREDBY | + +-----------------------+-----------------------+ + | **inside** | SDO_INSIDE | + +-----------------------+-----------------------+ + | **covers** | SDO_COVERS | + +-----------------------+-----------------------+ + | **overlaps** | SDO_OVERLAPS | + +-----------------------+-----------------------+ + | **equals to** | SDO_EQUAL | + +-----------------------+-----------------------+ + | **intersects** | SDO_ANYINTERACT | + +-----------------------+-----------------------+ + | **nn** | SDO_NN | + +-----------------------+-----------------------+ + +Funciones de tiempo para crear campos calculados +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. importante:: +**Solo Enterprise Edition** + + Time functions are available only for Enterprise Edition with SI licence. + +Si tiene licencia SI, en el asistente de campo calculado qbe hay funciones de tiempo disponibles. + +.. figura:: media/timeFunctions.png + + Time functions. + +Vea la siguiente tabla: + +.. \_timefunctions: +.. tabla:: Funciones de tiempo. +:widths: automático + + +-----------------------------------+-----------------------------------+ + | Function | Description | + +===================================+===================================+ + | **CURRENT_DATE()** | Returns current date | + +-----------------------------------+-----------------------------------+ + | **CURRENT_TIME()** | Returns current time | + +-----------------------------------+-----------------------------------+ + | **Hour(date)** | Returns hour from date | + +-----------------------------------+-----------------------------------+ + | **Second(date)** | Returns hour from date | + +-----------------------------------+-----------------------------------+ + | **Year(date)** | Returns year from date | + +-----------------------------------+-----------------------------------+ + | **Month(date)** | Returns month from date | + +-----------------------------------+-----------------------------------+ + | **Day(date)** | Returns day from date | + +-----------------------------------+-----------------------------------+ + | **get_quarter(date)** | Returns quarter of year for date | + +-----------------------------------+-----------------------------------+ + | **get_week(date)** | Returns week of year for date | + +-----------------------------------+-----------------------------------+ + | **get_day_of_the_week(date)** | Returns day of week for date | + +-----------------------------------+-----------------------------------+ + | **add_days(date, num)** | Add some days to date | + +-----------------------------------+-----------------------------------+ + | **add_hours(date,num)** | Add some hours to date | + +-----------------------------------+-----------------------------------+ + | **add_months(date,num)** | Add some months to date | + +-----------------------------------+-----------------------------------+ + | **add_years(date,num)** | Add some years to date | + +-----------------------------------+-----------------------------------+ + | **subtract_years(date,num)** | Remove some years from date | + +-----------------------------------+-----------------------------------+ + | **subtract_days(date,num)** | Remove some days from date | + +-----------------------------------+-----------------------------------+ + | **subtract_months(date,num)** | Remove some months from date | + +-----------------------------------+-----------------------------------+ + | **subtract_hours(date,num)** | Remove some hours from date | + +-----------------------------------+-----------------------------------+ + | **datediff_in_days(date)** | Difference in days between dates | + +-----------------------------------+-----------------------------------+ + | **datediff_in_hours(date)** | Difference in hours between dates | + +-----------------------------------+-----------------------------------+ + | **datediff_in_minutes(date)** | Difference in mins between dates | + +-----------------------------------+-----------------------------------+ + +.. figura:: media/currentDate.png + + Creating calculated field with function current_date(). + +.. figura:: media/currentTime.png + + Creating calculated field with function current_Time(). + +.. figura:: medios/hora.png + + Creating calculated field with function hour(date). + +.. figura:: medios/segundo.png + + Creating calculated field with function second(date). + +.. figura:: medios/año.png + + Creating calculated field with function year(date). + +.. figura:: medios/mes.png + + Creating calculated field with function month(date). + +.. figura:: medios/día.png + + Creating calculated field with function day(date). + +En la imagen de abajo, puede ver la lista de todos los campos calculados creados: + +.. figura:: media/advanceViewTime.png + + List of created calculated fields. + +En la siguiente imagen puedes ver el resultado de tu consulta: + +.. figura:: media/previewTime.png + + Result of the query. + +Subconsultas +\++++++++++ + +El **Motor QbE** también admite la definición y el uso de subconsultas de forma similar al lenguaje SQL. Como resultado, puede definir una subconsulta y utilizarla dentro de un filtro en asociación con el operador in/not in, como se muestra en la figura siguiente. Para crear una nueva subconsulta, que se puede utilizar como filtro dentro de la consulta principal, haga clic en |addSubqueries| , en la parte izquierda, en **Entidades derivadas** barra de herramientas. En la vista principal verá que puede agregar campos en subconsulta. + +.. |adioSubcuencias| imagen:: media/addSubquery.png +:ancho: 30 + +.. figura:: medios/subconsultas.png + + QbE subquery view. + +Puede volver fácilmente al qiery principal haciendo clic en **PRINCIPAL** en la barra de herramientas del editor de consultas. + +Para usar la subconsulta dentro de la consulta principal, simplemente elija entre el tipo de destino **Opción de subconsulta**De **Blanco** Elija la subconsulta que desee y establezca el tipo de condición (**EN** o **NO EN**). Ahora la subconsulta se utiliza para proporcionar valores dentro del filtro, de manera similar a las subconsultas SQL. + +.. figura:: media/image281.png + + QbE query: use of a subquery in a filter. + +Parámetros +\++++++++++ + +El **Motor QbE** también admite la definición y el uso de parámetros que se pueden utilizar para filtrar los datos mediante el filtro qbe. Para crear un nuevo parámetro, que se puede utilizar como filtro dentro de la consulta principal, haga clic en |parámetro| , en la barra de herramientas de consulta principal. + +.. |parámetro| imagen:: medios/parámetro.png +:ancho: 30 + +.. figura:: media/paramWizard.png + + QBE parameter view. + +Para usar el parámetro dentro de la consulta principal, simplemente elija entre el tipo de destino **Opción de parámetro** y desde **Blanco** elija el parámetro que desee. Ahora el parámetro se utiliza para proporcionar valores dentro del filtro. + +.. figura:: media/filterParam.png + + QbE query: use of a parameter in a filter. diff --git a/functionalities-guide/glossary-and-data-lineage/index.es.rst b/functionalities-guide/glossary-and-data-lineage/index.es.rst new file mode 100644 index 00000000..1285b55d --- /dev/null +++ b/functionalities-guide/glossary-and-data-lineage/index.es.rst @@ -0,0 +1,152 @@ +# Glosario y linaje de datos + +El **Glosario** la funcionalidad ofrece una forma de encontrar documentos navegando por una página de índice. + +## Gestión del glosario + +La gestión del glosario se divide en dos secciones. Una vez que ha iniciado sesión, el usuario puede encontrar los dos elementos del menú: **Definición del glosario** y **Uso del glosario**, como se muestra a continuación. + +.. figura:: media/image456.png + + Glossary menu items. + +Para crear un nuevo glosario, haga clic en el elemento de menú Definición de glosario que puede encontrar en el cuadro **Catálogos** sección del Knowage +interfaz. Como se muestra en la figura a continuación, la página contiene dos áreas: + +* **Palabra**: aquí hay una lista de términos. Estos últimos se utilizan como etiquetas para adjuntar a objetos analíticos como conjuntos de datos o documentos con el fin de vincular esos objetos al glosario; + +* **Glosario**: se pretende una estructura jerárquica formada por "Palabras". + +.. \_glossarydefwindow: +.. figura:: media/image457.png + + Glossary definition window. + +A continuación damos más información técnica sobre estos dos apartados. + +En el área "Palabra" se enumeran, si las hay, las palabras creadas en un momento anterior. Para explorar el detalle de cada uno de ellos, el usuario solo tiene que hacer clic derecho en él. Se mostrará un panel que contiene tres características, como se destaca en la figura a continuación. + +.. figura:: media/image458.png + + Exploring an existing word. + +Al explorar el detalle, aparecerá un asistente que mostrará las siguientes características: + +* descripción +* estado +* categoría +* una descripción de la fórmula, +* una lista de enlaces a otras palabras, +* una lista de atributos a los que se puede añadir un valor. + +El mismo panel se puede utilizar para modificar o eliminar la palabra. + +Para agregar una nueva palabra, haga clic en el icono "Más" disponible en la esquina derecha arriba del área "Palabra" como se muestra en la figura a continuación. Se abrirá un formato en la mitad derecha de la pantalla. Inserte "Nombre" y "Descripción", que son todos campos obligatorios y agregue detalles adicionales por necesidad. Luego haga clic en el botón Guardar. Observe que es posible buscar una "Palabra" utilizando el filtro dedicado disponible en la parte superior de la lista de palabras. Escriba una cadena en el cuadro y la investigación se iniciará automáticamente. Recuerde cancelar la cadena del cuadro para volver a la lista completa. + +.. \_addanewword: +.. figura:: media/image459.png + + Add a new word. + +En el área "Glosario" se enumeran, si los hubiera, todos los glosarios creados en un momento anterior. Para explorar un glosario existente, el usuario simplemente debe hacer clic en el elemento. La siguiente figura muestra un ejemplo. Aquí se subraya la estructura jerárquica del glosario. Para agregar un nuevo glosario, haga clic en el icono "Más" en la esquina superior derecha del área designada. + +.. figura:: media/image460.png + + Exploring a glossary from the menu. + +Al hacer clic con el botón derecho en la etiqueta del glosario como se muestra en la siguiente figura (lado derecho), el usuario puede agregar un nuevo hijo. Se abrirá el asistente "Nuevo nodo". Es obligatorio dar un Nombre al nodo mientras que se recomienda agregar un Código y una Descripción. Una vez que el usuario ha configurado los nodos, es posible agregar hijos o palabras a cada uno de ellos. + +.. \_newglossnewahild: +.. figura:: media/image46162.png + + (Left) New glossary wizard. (Right) Add a new child to the glossary. + +En particular, si uno hace clic derecho en el nombre del nodo, como en la siguiente figura, se abrirá un panel. Permite al usuario agregar un (o más) hijo o palabra al nodo. En ambos casos, el usuario deberá rellenar los campos obligatorios. Observamos que si el usuario elige agregar una palabra a través del elemento del panel, la palabra se creará desde cero y se agregará a la lista de Word después de guardarla. Para agregar una palabra existente, el usuario tiene que arrastrar y soltar la palabra de la lista al nodo. + +.. \_additemstonode: +.. figura:: media/image463.png + + Add items to the node(s). + +Complete la estructura de árbol del glosario. Utilice las características del panel de cada nodo o del propio glosario (recuerde hacer clic derecho en los elementos para obtener dicho panel) para agregar, modificar, inspeccionar o eliminar elementos. + +## Uso del glosario + +Esta funcionalidad se perfila de acuerdo con el rol de usuario e incluye características que permiten + +* visualizar el glosario, +* visualizar las asociaciones, +* gestionar las asociaciones entre el glosario y los documentos, +* gestionar las asociaciones entre el glosario y los conjuntos de datos. + +Seleccionar **Uso del glosario** en el menú contextual Catálogos, el usuario se encuentra con la página que se muestra a continuación. Aquí hay cuatro pestañas disponibles:**Glosario**, **Navegación**, **Gestión Documental** y **Administración de conjuntos de datos**. + +.. figura:: media/image464.png + + Glossary Usage graphic interface. + +La pestaña Glosario ofrece la posibilidad de visualizar los glosarios existentes. Seleccione un glosario del cuadro combinado disponible en esta página para inspeccionar sus elementos. Utilice el icono con una "i" con un círculo para visualizar los detalles del elemento relacionado, como se muestra a continuación. Tenga en cuenta que está habilitada la posibilidad de buscar una palabra utilizando el cuadro de investigación configurado. + +.. figura:: media/image465.png + + Visualization of glossary details. + +Las rutas de navegación se pueden explorar en la segunda pestaña. Esta ventana tiene una lógica asociativa que facilita la navegación por las asociaciones. En otros términos, aquí es posible verificar las relaciones entre documentos o conjuntos de datos y palabras de un glosario. Un +ejemplo se da en la siguiente figura. + +.. figura:: media/image466.png + + Navigation tab window. + +Para utilizar esta funcionalidad, seleccione un glosario utilizando el cuadro combinado designado disponible en la parte superior de la columna "palabra". La ventana mostrará todas las palabras asociadas a ese glosario. Al seleccionar una de esas palabras, se mostrará una lista de documentos en el área en el medio de la página. Utilice el icono i con un círculo para inspeccionar los detalles del documento y, además, para ejecutarlo. De hecho, el botón "Ejecutar" está disponible en la esquina inferior derecha del panel de detalles, como se muestra a continuación. + +.. figura:: media/image46768.png + + Execution documents by means of the glossary. + +Los filtros elegidos por el usuario se pueden eliminar a través del icono rojo del filtro o seleccionando el **Borrar filtro** botón |image475| ubicado en la esquina superior derecha de la lista de palabras. + +.. |imagen475| imagen:: media/image469.png +:ancho: 30 + +Tenga en cuenta que es posible inspeccionar los detalles de cada elemento utilizando el icono específico. + +La pestaña Gestión de documentos es el lugar donde establecer las asociaciones entre los documentos analíticos y las palabras de un glosario. Esta funcionalidad se perfila a través de la autorización **Administrar glosario técnico**. + +La página se compone de tres colums: el de "documentos" uno a la izquierda, la "palabra" en el centro y el "glosario" a la derecha. Para asociar una palabra a un documento o ver qué palabras están relacionadas con él, el usuario debe seleccionar un documento de la lista de la columna del lado izquierdo. Luego es obligatorio seleccionar un glosario del cuadro combinado disponible en la columna del lado derecho. Finalmente, arrastre y suelte palabras desde el árbol del glosario hasta la columna "palabra" en el centro de la página. Tenga en cuenta que el usuario debe arrastrar y soltar la palabra al principio de la lista: cuando aparece un cuadro azul claro con bordes punteados es posible finalizar la acción. Para anular la selección, el usuario puede hacer clic en el icono |image476| aparte de cada palabra. Este procedimiento se resume en la figura a continuación. + +.. |imagen476| imagen:: media/image470.png +:ancho: 30 + +.. figura:: media/image47172.png + + Managing the association with a document: (Left) Select the documnet. (Right) Associate one (or more) word(s). + +Si uno vuelve a la pestaña de navegación y selecciona el glosario utilizado en el paso anterior, es posible verificar la asociación que acaba de establecer. + +Del mismo modo, la función de administración de conjuntos de datos permite al usuario establecer las asociaciones entre conjuntos de datos y glosarios. La siguiente figura muestra un ejemplo. La ventana se divide en cuatro áreas: **Conjunto de datos**, **Conjunto de datos/Word**, **Columna/Palabra** y **Glosario**. Primero, el usuario debe seleccionar un conjunto de datos en el área izquierda. El conjunto de datos elegido se resalta y sus campos aparecen en el área Columna/Word. Ahora, el usuario selecciona un glosario usando el cuadro combinado en el área del lado derecho. Finalmente, el usuario puede arrastrar y soltar palabras desde el árbol del glosario al conjunto de datos o a los campos individuales del conjunto de datos. + +.. \_datasetmanagmtab: +.. figura:: media/image473.png + + Dataset management tab. + +Una vez que los conjuntos de datos o los documentos están vinculados a los glosarios, el usuario puede ingresar al elemento de menú Uso del glosario para navegar fácilmente por el +elementos dentro de la suite Knowage. + +## Funcionalidad de Ayuda en línea + +El usuario puede inspeccionar la asociación de un elemento analítico específico (conjunto de datos, documento o modelo) utilizando el **Ayuda en línea** funcitonalidad. Se puede llegar a este último: + +* desde el explorador de documentos, +* desde la barra de herramientas de cada documento, una vez iniciado, +* de cada conjunto de datos, +* de cada entidad del modelo Qbe, +* de los informes Birt, +* desde la cabina. + +Como ejemplo, mostramos en la figura a continuación la interfaz gráfica que el usuario encontrará una vez que haya lanzado un documento y desee utilizar la funcionalidad de Ayuda en línea. + +.. figura:: media/image474.png + + Help Online wizard. diff --git a/functionalities-guide/hiearchies/index.es.rst b/functionalities-guide/hiearchies/index.es.rst new file mode 100644 index 00000000..fec262a0 --- /dev/null +++ b/functionalities-guide/hiearchies/index.es.rst @@ -0,0 +1,567 @@ +# Jerarquías + +El Editor de jerarquías le permite administrar datos estructurados jerárquicamente. + +Consta de tres pestañas: MASTER, TECHNICAL y BACKUP. +Los dos primeros muestran a la derecha los objetos editables en forma de árboles, mientras que a la izquierda los objetos de origen con los que actualizar los destinos (pueden ser tablas o árboles: la tabla muestra los datos (hoja) recuperándolos directamente de la dimensión asociada mientras que los árboles muestran otras jerarquías ya creadas). + +PESTAÑAS + +``` + +In detail: + +- **The MASTER tab**: allows the creation of 'master' hierarchies as well as the modification of the same or of the technical hierarchies starting directly from the data read from the reference dimension (leaves). +- **The TECHNICAL tab**: allows the creation of new technical hierarchies and their modification starting from other existing hierarchies (master or technical) + +FILTERS +~~~~~~~ + +.. figure:: media/image1.png + + Filters. + +In each tab there is a dynamic filter section useful for selecting the data to manage (both the dimension table and the trees) +Eg. for the size of the CDC it is possible to set: + +- **a validity date** against which the *begin_dt* and *end_dt* dates will be compared. By default it shows today's date (optional) +- **a hierarchy date** against which the *hier_begin_dt* and *hier_end_dt* dates of the dimension will be compared. Note that this is an optional date, managed through the configuration and provided only with the dimension DIM_CDC. +- **a date after** which the records are to be considered. Again it will be compared with *begin_dt* (but without *end_dt*). +- **a 'Show missing elements' flag** that allows you to exclude from the selection the leaves already used in the source or target element loaded on the left or right with respect to the object on which the filters are applied. + +These same filters will be applied by the system to manage the creation of masters and their synchronization. + + +MASTER hierarchies +``` + +.. figura:: media/image2.png + +Jerarquías MASTER. + +Para crear una nueva jerarquía MASTER, configure los filtros correctamente para seleccionar las hojas (por ejemplo, CDC) que desea insertar (tabla izquierda) y, a continuación, abra la ventana emergente de creación MASTER con el botón apropiado + +.. figura:: media/image3.png + +CREAR JERARQUÍA MAESTRA. + +Establezca la configuración básica (código, nombre, descripción y año) y, a continuación, presione GUARDAR: + +.. figura:: media/image4.png + +Configuración básica MASTER. + +No establezca las fechas de inicio y finalización si planea usar la función de sincronización (si aparecen en la ventana emergente). Esto reportará las mismas fechas de validez que las hojas recuperadas de la dimensión. +Defina la estructura de la jerarquía llevando los elementos de la dimensión a la derecha como niveles. Tenga en cuenta que el último nivel debe ser el código/nombre de la hoja. + +Con el botón SAVE se activa la creación de la nueva jerarquía MASTER, que luego se hace visible y modificable en el lado derecho en forma de árbol: + +Cada elemento del árbol (nodo u hoja) tiene un menú contextual con funciones activas (una información sobre herramientas en cada elemento individual resaltará la funcionalidad): + +.. figura:: media/image5.png + +Jerarquía MASTER. + +## Menú Nodo + +.. figura:: media/image6.png + +Menú Nodo. + +En los nodos individuales es posible: + +* Agregar un nuevo subnodo +* Modificar el nodo en sí (se abre una ventana emergente con los campos editables activos) +* Eliminar el propio nodo +* Ver el detalle completo del nodo + +## Menú de hojas + +.. figura:: media/image7.png + +Menú de hojas. + +En hojas sueltas es posible: + +* Duplicar la hoja: si así lo requiere la configuración, se activará un popup que permitirá la modificación del detalle y la validez temporal. +* Modifique la hoja en sí (también aquí se activará una ventana emergente con los campos editables) +* Eliminar la hoja en sí +* Ver el detalle completo de la hoja + +## Gestión de la sincronización + +La función de sincronización se proporciona solo para las jerarquías MASTER y permite que la jerarquía se actualice agregando nuevas hojas o modificando las existentes. + +este es el enfoque utilizado: + +* el usuario selecciona a través de los filtros las hojas con las que quiere actualizar la jerarquía seleccionada a la derecha y pulsa el botón SYNCRONIZE debajo de la tabla. Todos los elementos de la tabla de la izquierda se manejarán en el proceso de sincronización. +* el sistema recupera los datos seleccionados y los datos de la jerarquía y aplica un concepto de fusión, es decir, añade a las hojas existentes las presentes en la versión anterior de la jerarquía. Si una hoja ya está presente, la versión de la dimensión recibida en la entrada se mantiene y sin duda estará más actualizada. + +## Gestión de propagación de cambios entre MASTER y TÉCNICO + +Si se ha modificado un nodo de la jerarquía maestra con el que se han modificado una o más jerarquías técnicas (con arrastrar y soltar una hoja recuperada de la tabla), se propone propagar estos cambios también a las jerarquías técnicas. +Esta característica abre una ventana emergente cuando el usuario libera la hoja en el nodo en cuestión que propone una lista con todos los nodos de las jerarquías técnicas en las que está presente el nodo recién modificado. En este punto, el usuario puede seleccionar todo, alguna o ninguna jerarquía en la que propagar el cambio. + +.. figura:: media/image8.png + +Objetivo de las jerarquías. + +En el botón OK se añadirá la hoja a la jerarquía en el punto en el que se suelta el ratón (se hayan seleccionado o no las jerarquías a propagar) y con el botón SAVE el cambio se aplicará tanto a la jerarquía MASTER como a las TECHNIQUES (siempre si y solo si es necesario). + +Jerarquías técnicas + +``` + +.. figure:: media/image9.png + + Technical Hierarchies. + +The technical hierarchies can only be created in the TECHNICAL tab using the appropriate CREATE button, but they can also be modified in the MASTER tab when you want to add the leaves directly; alternatively it is possible to add portions of existing hierarchy trees with a simple drag & drop. + +The management of filters and context menus are the same as for the master hierarchies, so we refer to the previous sections for further details + +Backup +------- + +.. figure:: media/image10.png + + Backup. + +Each time the trees are saved, it is possible to make a backup of the current version before modifications. It is an activity done by default but you can disable it by deactivating the Backup check next to the SAVE button in the first two tabs. + + + +In the Backup tab you can view all the saves made related to a specific hierarchy of the selected dimension. +For each line displayed in this interface it is possible to: + +- change the name and description (in case you want to give a more logical meaning to the save) +- restore or restore the selected version +- delete the backup itself + +.. warning:: + Since a complete copy of the hierarchy is made for each backup, it is recommended to periodically delete the oldest backups to free up space on the database. + + +Configuration management +``` + +Detrás del editor de jerarquías hay un archivo xml de configuración que guía la gestión de toda la interfaz. +Este archivo se denomina jerarquías.xml y se puede encontrar en el servidor de aplicaciones en la carpeta de recursos del inquilino de referencia `TOMCAT_HOME/resources//hierarchies/` camino. + +La sintaxis es XML y las etiquetas principales son: + +.. code-block:: xml +:linenos: +:caption: Etiquetas principales del XML utilizadas para la configuración. + + + + + + + + ... + ... + ... + ... + + + + +Para guiar son las dimensiones por lo tanto para cada dimensión se especifica: + +\+--------------------------------+---------------------------------------------------+--------------+ +| PROPIEDADES | | DE VALOR NOTAS DE VALOR | +\+================================+===================================================+==============+ +| nombre | Cuerda. El nombre físico de la dimensión de origen | | obligatoria +\+--------------------------------+---------+-----------------------------------------+--------------+ +| etiqueta | Cuerda. La etiqueta de cota que se muestra en la gui | | obligatoria +\+--------------------------------+---------+-----------------------------------------+--------------+ +| prefijo | Cuerda. El prefijo para el | físico estándar | obligatoria +| | columna | obligatorio | +\+--------------------------------+---------+-----------------------------------------+--------------+ +| datasource | Cuerda. La etiqueta del origen de datos definido | | obligatoria +| | en Knowage donde existen las tablas | | +\+--------------------------------+-----------------------+---------------------------+--------------+ + +## Etiqueta de tabla de jerarquía + +.. code-block:: xml +:linenos: +:caption: Etiqueta HIERARCHY_TABLE y sus propiedades. + + + +Define la referencia de la tabla física de jerarquía. + + +--------------------------------+------------------------------------------------------------+--------------+ + | PROPERTIES | VALUE | VALUE NOTES | + +================================+============================================================+==============+ + | NAME | String. The physical name of the target hierarchical table.| Mandatory | + +--------------------------------+------------------------------------------------------------+--------------+ + | PRIMARY_KEY | String. String. The name of the primary key for the target | Mandatory | + | | table Optional. If isn't present the db must be able to | | + | | manage autoincrement. | | + +--------------------------------+------------------------------------------------------------+--------------+ + +## Etiqueta de clave externa de jerarquía + +.. code-block:: xml +:linenos: +:caption: Etiqueta HIERARCHY_FK y su propiedad. + + + +Define la clave externa de jerarquía para vincularla a la tabla de cotas. + + +--------------------------------+------------------------------------------------------------+--------------+ + | PROPERTIES | VALUE | VALUE NOTES | + +================================+============================================================+==============+ + | NAME | String. The name of the foreign key from the source table | Mandatory | + | | to the target table. | | + +--------------------------------+------------------------------------------------------------+--------------+ + +## Etiqueta Configs + +.. code-block:: xml +:linenos: +:caption: Etiqueta CONFIGS y su propiedad. + + + + + + + + + + + + + + + + + + +Contiene toda la configuración genérica posible para la administración de la GUI + + +-----------------+---------------------------------------------------------------+---------------------------------------------------------+ + | PROPERTY | VALUE | NOTE | + +=================+===============================================================+=========================================================+ + | NUM_LEVELS | Numeric. The number of maximum hierarchical levels. | Mandatory. The target table must have _CD_LEVx | + | | | where x is a counter from 1 to NUM_LEVELS value. | + | | | The same for _NM_LEVx and so on. | + +-----------------+---------------------------------------------------------------+---------------------------------------------------------+ + | ALLOW_DUPLICATE | Boolean. True if the tool can duplicate totally the leaf. | Mandatory. | + +-----------------+---------------------------------------------------------------+---------------------------------------------------------+ + | UNIQUE_NODE | Boolean. True if the leaves must have a unique hashcode as id.| Optional. Pay attention to the dimension of Ids fields | + | | | because the hash code could be long. | + +-----------------+---------------------------------------------------------------+---------------------------------------------------------+ + | TREE_NODE_CD | String. The column of the target table | Mandatory. | + | | that will be used as code on the tree. | Not specify level i.e. _CD_LEV | + +-----------------+---------------------------------------------------------------+---------------------------------------------------------+ + | TREE_NODE_NM | String. The column of the target table | Mandatory. | + | | that will be used as name on the tree. | Not specify level i.e. _NM_LEV | + +-----------------+---------------------------------------------------------------+---------------------------------------------------------+ + | TREE_LEAF_ID | String. The column of the target table | Mandatory. | + | | that will be used as id of the leaf on the tree. | | + +-----------------+---------------------------------------------------------------+---------------------------------------------------------+ + | TREE_LEAF_CD | String. The column of the target table | Mandatory. | + | | that will be used as code of the leaf on the tree. | | + +-----------------+---------------------------------------------------------------+---------------------------------------------------------+ + | TREE_LEAF_NM | String. The column of the target table | Mandatory. | + | | that will be used as name of the leaf on the tree. | | + +-----------------+---------------------------------------------------------------+---------------------------------------------------------+ + | DIMENSION_ID | String. The column of the source table | Mandatory. | + | | that will be used as id of the dimension. | | + +-----------------+---------------------------------------------------------------+---------------------------------------------------------+ + | DIMENSION_CD | String. The column of the source table | Mandatory. | + | | that will be used as code of the dimension. | | + +-----------------+---------------------------------------------------------------+---------------------------------------------------------+ + | DIMENSION_NM | String. The column of the source table | Mandatory. | + | | that will be used as name of the dimension. | | + +-----------------+---------------------------------------------------------------+---------------------------------------------------------+ + | FILL_EMPTY | Boolean. If true set the filling of the empty node | Optional. It's used in master creation context | + | | with a default value. | where the leaf is fixed to a specific level. | + +-----------------+---------------------------------------------------------------+---------------------------------------------------------+ + | FILL_VALUE | String. Specify the value of default used | Optional. | + | | for filling empty nodes. | | + +-----------------+---------------------------------------------------------------+---------------------------------------------------------+ + +## Etiqueta de filtros tenues (opcional) + +.. code-block:: xml +:linenos: +:caption: Etiqueta DIM_FILTERS y sus propiedades. + + + + + ... + + +Define filtros opcionales en la sección de cota + + +------------+------------------------------------------------------+----------------------------------------------------------------+ + | PROPERTY | VALUE | NOTE | + +============+======================================================+================================================================+ + | TYPE | String. The type of the filter. | Mandatory. Depending from the type a different | + | | Could be String, Number or Date. | widget will be shown (input text, calendar, ..). | + +------------+------------------------------------------------------+----------------------------------------------------------------+ + | NAME | String. The label visualized near the filter element.| Mandatory. | + +------------+------------------------------------------------------+----------------------------------------------------------------+ + | CONDITIONx | String. The formula of the filter. | Mandatory. Could be are present more conditions element | + | | | ie. CONDITION1, CONDITION2,... | + | | | All these conditions will be apply (without elaboration) | + | | | on the final select query defined dynamically from the system. | + +------------+------------------------------------------------------+----------------------------------------------------------------+ + | DEFAULT | String. The default value for the filter | Optional. | + +------------+------------------------------------------------------+----------------------------------------------------------------+ + +## Etiqueta de campos oscuros (obligatorio) + +.. code-block:: xml +:linenos: +:caption: Etiqueta DIM_FIELDS y sus propiedades. + + + ... + + + + ... + + +Especifica todos los campos de dimensión administrados por la GUI. + + +----------+-----------------------------------------------------------------------------+------------+ + | PROPERTY | VALUE | NOTE | + +==========+=============================================================================+============+ + | ID | String. The column of the source dimension table | Mandatory. | + | | that will be managed through the GUI. | | + +----------+-----------------------------------------------------------------------------+------------+ + | NAME | Boolean. True if the field must be shown in the table, false otherwise. | Mandatory. | + +----------+-----------------------------------------------------------------------------+------------+ + | VISIBLE | True if the field could be editable from the user, false otherwise. | Mandatory. | + +----------+-----------------------------------------------------------------------------+------------+ + | EDITABLE | Boolean. True if the field could be editable from the user, false otherwise | Mandatory. | + +----------+-----------------------------------------------------------------------------+------------+ + | TYPE | String. The type of the field. | Mandatory. | + | | Could be String, Number or Date. | | + +----------+-----------------------------------------------------------------------------+------------+ + | PARENT | Boolean. True if the field contains the parent | Optional. | + | | reference information for a recursive management. | | + +----------+-----------------------------------------------------------------------------+------------+ + +## Etiqueta Hier Fields + +Obligatorio. Especifica todos los campos de dimensión administrados por la GUI. + +Se compone de tres secciones: GENERAL_FIELDS, NODE_FIELDS y LEAF_FIELDS. + +.. code-block:: xml +:linenos: +:caption: Etiqueta HIER_FIELDS y sus propiedades. + + + ... + ... + ... + + +## Campos generales + +.. code-block:: xml +:linenos: +:caption: Etiqueta GENERAL_FIELDS y sus propiedades. + + + + + + + + + +Define todos los campos genéricos de la jerarquía + + +----------+----------------------------------------------------------------------------------------+------------+ + | PROPERTY | VALUE | NOTE | + +==========+========================================================================================+============+ + | ID | String. The column of the target hierarchy table that will be managed through the GUI. | Mandatory. | + +----------+----------------------------------------------------------------------------------------+------------+ + | NAME | String. The label of the element shown in the GUI. | Mandatory. | + +----------+----------------------------------------------------------------------------------------+------------+ + | VISIBLE | Boolean. True if the field must be shown in the table, false otherwise. | Mandatory. | + +----------+----------------------------------------------------------------------------------------+------------+ + | EDITABLE | Boolean. True if the field could be editable from the user, false otherwise. | Mandatory. | + +----------+----------------------------------------------------------------------------------------+------------+ + | REQUIRED | Boolean. True if the field is mandatory and the user must insert any values; | Optional. | + | | false otherwise. | | + +----------+----------------------------------------------------------------------------------------+------------+ + | TYPE | String. The type of the field. | Mandatory. | + | | Could be String, Number or Date. | | + +----------+----------------------------------------------------------------------------------------+------------+ + +## Campos de nodo + +.. code-block:: xml +:linenos: +:caption: Etiqueta NODE_FIELDS y sus propiedades. + + + + + + + + +Define todos los campos para los nodos + + +--------------+-------------------------------------------------------------------------------+------------+ + | PROPERTY | VALUE | NOTE | + +==============+===============================================================================+============+ + | ID | String. The column of the target hierarchy table | Mandatory. | + | | that will be managed through the GUI. | | + +--------------+-------------------------------------------------------------------------------+------------+ + | SINGLE_VALUE | Boolean. True if the field is present any times | Mandatory. | + | | like the NUM_LEVELS property defines; false otherwise. | | + +--------------+-------------------------------------------------------------------------------+------------+ + | NAME | String. The label of the element shown in the GUI. | Mandatory. | + +--------------+-------------------------------------------------------------------------------+------------+ + | VISIBLE | Boolean. True if the field must be shown in the table, | Mandatory. | + | | false otherwise. | | + +--------------+-------------------------------------------------------------------------------+------------+ + | EDITABLE | Boolean. True if the field could be editable from the user, | Mandatory. | + | | false otherwise. | | + +--------------+-------------------------------------------------------------------------------+------------+ + | REQUIRED | Boolean. True if the field is mandatory and the user must insert any values; | Optional. | + | | false otherwise | | + +--------------+-------------------------------------------------------------------------------+------------+ + | TYPE | String. The type of the field. Could be String, Number or Date. | Mandatory. | + +--------------+-------------------------------------------------------------------------------+------------+ + +## Campos de hojas + +.. code-block:: xml +:linenos: +:caption: Etiqueta LEAF_FIELDS y sus propiedades. + + + + + + + + + + + +Define todos los campos de la hoja + + +----------+-------------------------------------------------------------------------------+------------+ + | PROPERTY | VALUE | NOTE | + +==========+===============================================================================+============+ + | ID | String. The column of the source dimension table | Mandatory. | + | | that will be used as id. | | + +----------+-------------------------------------------------------------------------------+------------+ + | NAME | String. The label of the element shown in the GUI | Mandatory. | + +----------+-------------------------------------------------------------------------------+------------+ + | VISIBLE | Boolean. True if the field must be shown in the table, | Mandatory. | + | | false otherwise. | | + +----------+-------------------------------------------------------------------------------+------------+ + | EDITABLE | Boolean. True if the field could be editable from the user, | Mandatory. | + | | false otherwise. | | + +----------+-------------------------------------------------------------------------------+------------+ + | REQUIRED | Boolean. True if the field is mandatory and the user must insert any values; | Optional. | + | | false otherwise | | + +----------+-------------------------------------------------------------------------------+------------+ + | TYPE | String. The type of the field. Could be String, Number or Date. | Mandatory. | + +----------+-------------------------------------------------------------------------------+------------+ + +DETALLE DE LOS FILTROS + +``` + +Below is a list of the filters that can be applied through the GUI on the MASTER tab with the details of the queries performed by the system to retrieve information related to dimensions in order to explain how the filters set through the GUI affect the result. +In general, all filters are applied with the 'AND' logic, so the records must satisfy ALL the defined settings to be selected. + +Note: for the selection of dates it is recommended to use the date-picker in order to be independent of the managed format due to the active language. + +BASIC FILTERS +-------------- + +1. Size +^^^^^^^ + +.. figure:: media/image11.png + + Size. + + +As mentioned previously, the dimension is mandatory for the recovery of the data to be managed. The usable values ​​are retrieved from the configuration file (see the 'Configuration Management' paragraph defined above). + +2. Filter on validity date +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. figure:: media/image12.png + + Filter on validity date. + +Unlike the dimension, the effective date becomes optional if other dates are set in the optional filter panel. +  +By setting the validity date, all 'valid' records will be retrieved from the specified size, i.e. with the BEGIN_DT attribute less than or equal to the specified date and the END_DT attribute greater than or equal to the specified value. + + +OPTIONAL FILTERS +----------------- + +3. Filter on a given hierarchy +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. figure:: media/image13.png + + Filter on a given hierarchy. + + +The hierarchy date is the earliest definable date in the optional filter panel. This means that not all dimensions can set it and that its definition - and therefore the type of condition to be applied - is configured within the configuration file (see the 'Dim Filters tag' paragraph specified above). + +Therefore, according to the current configuration, by setting the hierarchy date, all the records with the 'valid' hierarchy date will be retrieved from the specified dimension, i.e. with the BEGIN_HIER_DT attribute less than or equal to the specified date and the END_HIER_DT attribute greater than or equal to the value specified. + +This means if an element of the dimension were created with a given hierarchy after the one set, it would not be considered. + +4. Filter on date 'after ...' +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. figure:: media/image14.png + + Filter on date 'after ...'. + + +The date 'after ..' is also part of the optional filter panel (see the 'Dim Filters tag' paragraph specified above). + +Therefore, according to the current configuration, by setting the date 'after ...', all the 'valid' records from that date onwards will be retrieved from the specified size or with the BEGIN_DT attribute greater than or equal to the specified date; in this case the END_DT attribute is not considered. + +5. Filter 'Show missing elements ...' +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. figure:: media/image15.png + + Filter 'Show missing elements ...'. + + +In order to choose the 'Show missing elements' option, the user must previously select an existing hierarchy to compare with (right side of the GUI). +At this point, considering the other options set, all the records that are not yet present on the target hierarchy with the same conditions will be selected. + +6. Compound filters +^^^^^^^^^^^^^^^^^^^ + +.. figure:: media/image15.png + + Compound filters. + +Obviously it is possible to apply more filters at the same time; this means that only the records that satisfy ALL the conditions set will be recovered. +  +This example shows the application of the validity logic both on the generic dates of the record and on those of the hierarchy. +``` diff --git a/functionalities-guide/index.es.rst b/functionalities-guide/index.es.rst new file mode 100644 index 00000000..eff2cff2 --- /dev/null +++ b/functionalities-guide/index.es.rst @@ -0,0 +1,33 @@ +Funcionalidades +\################## + +.. toctree:: +:caption: Tabla de contenido + +basic-data-access/index.rst +advanced-data-access/index.rst +behavioural-model/index.rst +analytical-document/index.rst +gráfico/index.rst +cockpit/index.rst +free-inquiry/index.rst +meta-web/index.rst +registro/index.rst +birt-reporting/index.rst +jasper-reporting/index.rst +location-intelligence/index.rst +svg-document-visualization/index.rst +datamining/index.rst +análisis multidimensional/index.rst +análisis what-if/index.rst +glosario-y-data-lineage/index.rst +dossier/index.rst +jerarquías/index.rst +key-performance-indicator/index.rst +cuadro de mandos/index.rst +alerta/index.rst +news-management/index.rst +resource-manager/index.rst +dataset-preview/index.rst +widget-gallery/index.rst +data-preparation/index.rst diff --git a/functionalities-guide/jasper-reporting/index.es.rst b/functionalities-guide/jasper-reporting/index.es.rst new file mode 100644 index 00000000..4c114707 --- /dev/null +++ b/functionalities-guide/jasper-reporting/index.es.rst @@ -0,0 +1,80 @@ +# Informes de Jasper + +Jasper es una herramienta de informes independiente desarrollada por la Comunidad jaspersoft. Un ejemplo del informe Jasper se representa en la siguiente figura. Jasper Report Engine administra plantillas de informes de Jasper dentro de Knowage Server. Una plantilla de informe para Jasper es un archivo de texto con extensión .jrxml que puede ser modificado manualmente por usuarios muy expertos mediante la edición de código XML. De lo contrario, iReport, un diseñador gráfico de plantillas, se proporciona a todos los desarrolladores que desean diseñar fácilmente un informe para este motor. + +.. \_exjasperreprt: +.. figura:: media/image342.png + + Example of a Jasper report. + +Plese tenga en cuenta que este motor está disponible solo en KnowageER. + +## Definición de documentos\* + +A diferencia del diseñador BIRT, iReport no está integrado en Eclipse. Por lo tanto, antes de comenzar a desarrollar el informe, debe descargarlo del sitio web http://community.jaspersoft.com/project/ireport-designer/releases. + +.. nota:: +**Descarga de iReport** + + Download the iReport designer at . Knowage support any kind of version. + +Luego tendrá que establecer la ruta al diseñador de iReport en Knowage Studio. Abra Ventana > Preferencias > Configuración del Editor de iReport y establezca la ruta correcta al archivo ireport.exe. + +.. figura:: media/image343.png + + iReport Configuration in Knowage Studio. + +Al igual que en el caso de un informe BIRT, el diseño y la implementación de un informe Jasper con Knowage Studio consta de los siguientes pasos: + +* crear el documento vacío, +* cambiar a la perspectiva del diseñador de informes, +* crear el origen de datos, +* crear el conjunto de datos, +* diseñar el informe a través de la interfaz gráfica, +* implementar el informe en el servidor. + +Para crear un nuevo informe de Jasper, haga clic con el botón derecho en el botón **Análisis de Negocio** y seleccione **Informe** > **Informe con Jasper**. Esto abrirá un editor donde puede elegir un nombre para su documento. El nuevo documento se creará en la carpeta Análisis de negocio. + +Haga doble clic en el informe para abrir el editor: el editor de iReport se iniciará dentro de Knowage Studio. Ahora está listo para comenzar a desarrollar su informe. + +Los siguientes pasos consisten en la creación de un origen de datos y de un conjunto de datos. Como se describe en la sección "Definición de conjunto de datos", Knowage Studio permite el desarrollo de documentos analíticos utilizando conjuntos de datos internos o externos. En este ejemplo mostraremos cómo crear un informe con un conjunto de datos interno. + +Haga clic en el pequeño icono |image348| de la barra de menús. Se abrirá el editor de creación de orígenes de datos. + +.. |imagen348| imagen:: media/image344.png +:ancho: 30 + +Seleccione un origen de datos JDBC, establezca los parámetros adecuados y asigne un nombre al origen de datos. En la figura siguiente se muestran los asistentes que se presentan en este procedimiento. + +.. figura:: media/image345.png + + Creation of a JDBC data source in a Jasper report. + +Una vez que haya definido el origen de datos, cree el conjunto de datos. Tenga en cuenta que Jasper solo permite un conjunto de datos principal. Por cierto, se pueden agregar conjuntos de datos secundarios si es necesario. Haga clic con el botón derecho en el elemento de informe y seleccione **Agregar conjunto de datos**. El editor de conjuntos de datos le guiará a través de la definición del conjunto de datos. Puede editar manualmente la consulta SQL o utilizar la herramienta de consulta de diseño proporcionada por iReport. + +El árbol situado en la parte izquierda de la ventana muestra los elementos del informe. A la derecha, el **Paleta** muestra todos los elementos gráficos que puede agregar. Puede elegir ver su informe dentro del **Diseñador**, para inspeccionar el **XML** código o para mirar el **Vista previa** de su informe. Si hace clic en el |image350| puede editar y obtener una vista previa de la consulta. Como puede ver, el diseñador de iReport permite la creación de informes complejos, con diferentes elementos gráficos como pestañas cruzadas, gráficos, imágenes y diferentes áreas de texto. Ahora vemos ahora en breve cómo diseñar un informe muy simple, es decir, un informe que contiene una tabla que muestra datos del conjunto de datos definido. + +.. |image350| imagen:: media/image346.png +:ancho: 30 + +.. figura:: media/image347.png + + Data Set definition. + +Para crear una tabla, haga clic en el elemento de la paleta y utilice el asistente. La siguiente figura muestra la interfaz del editor de Jasper. + +.. figura:: media/image348.png + + iReport graphical editor. + +Para insertar columnas de conjunto de datos en el informe, utilice la sintaxis que se muestra en la sintaxis siguiente para insertar columnas de conjunto de datos. + +.. code-block:: bash +:linenos: +:caption: Sintaxis para insertar columnas de dataset. + + $F{name_of_dataset_column} + +Una vez que se ha desarrollado el documento, los usuarios técnicos pueden utilizar el servicio de implementación de Knowage Studio para registrar fácilmente el informe con su plantilla en Knowage Server. Alternativamente, cualquier plantilla válida de Jasper (desarrollada con o sin Knowage Studio) se puede cargar directamente en Knowage Server utilizando la interfaz web para la gestión de documentos. + +Esta sección no proporciona más detalles sobre el desarrollo gráfico, ya que se centra en aspectos específicos de Knowage Jasper Report Engine. Todas las funcionalidades estándar de Jasper funcionan con Jasper Report Engine. Para obtener una visión general completa de la herramienta de informes de Jasper y una guía detallada para desarrolladores, consulte la documentación oficial en `http://community.jaspersoft.com/`. diff --git a/functionalities-guide/key-performance-indicator/index.es.rst b/functionalities-guide/key-performance-indicator/index.es.rst new file mode 100644 index 00000000..146fb6dc --- /dev/null +++ b/functionalities-guide/key-performance-indicator/index.es.rst @@ -0,0 +1,321 @@ +# Indicador clave de rendimiento + +KPI significa Indicador Clave de Rendimiento. Denota un conjunto de métricas, generalmente derivadas de medidas simples, que permiten a los gerentes tomar una instantánea de los aspectos clave de su negocio. Las principales características de los KPI siguen: + +* indicadores resumidos, +* cálculos complejos, +* umbrales que respalden la evaluación de los resultados, +* objetivos de referencia, +* fácil de usar pero que requiere habilidades más específicas para diseñarlo, +* asociación con alarmas, +* no se utiliza necesariamente para el análisis en tiempo real, +* puede referirse a un marco de tiempo específico. + +Por estas razones, los KPI siempre son definidos por analistas expertos y luego utilizados para analizar el rendimiento a través de vistas sintéticas que seleccionan y describen solo información significativa. + +Knowage permite la configuración de un documento KPI gracias a un documento específico **Motor KPI**. El valor crítico (o valores) se puede calcular y visualizar a través de las funcionalidades disponibles en la sección 'Modelo KPI' del área de menú Knowage (consulte la siguiente figura). + +## Desarrollo de KPI + +Introducimos la herramienta KPI dividiendo el tema en pasos. Resumimos brevemente aquí los argumentos que cubriremos en las siguientes secciones para tener una visión general de la implementación de KPI. + +* **Definición de la medida**: es necesario definir primero las medidas y atributos, eventualmente con parámetros, para calcular el valor crítico de interés. +* **Definición de KPI**: aquí se calcula el valor solicitado a través de una fórmula utilizando las medidas y atributos establecidos en el paso anterior y configurar umbrales. +* **Blanco**: es posible monitorear el valor de uno o más KPI comparándolo con un valor fijo adicional. +* **Schedulation**: puede programar la ejecución de uno o más KPI, eventualmente filtrados por condiciones. +* **Creación de documentos**: por último, se desarrolla el documento KPI. + +Por lo tanto, entramos en más detalles. + +**Definición de la medida.** El primer paso es crear una nueva medida o regla. Escoger **Definición de medida/regla** desde el menú contextual de la página principal, como se muestra a continuación. + +.. \_measureruledefmenu: +.. figura:: media/image121.png + + Measure/Rule Definition menu item. + +Haga clic en el icono "Más" para establecer una nueva medida/regla. Se abre una página del editor de consultas. Tenga en cuenta que una vez seleccionado el origen de datos, al presionar simultáneamente la tecla CRTL y la barra espaciadora se abre un menú contextual que contiene las columnas de origen de datos disponibles y las palabras clave de la base de datos. Consulte la siguiente figura para tener un ejemplo. + +.. figura:: media/image122.png + + Editing the query when defining a KPI. + +Cada regla se basa en una consulta a la que puede agregar marcadores de posición. Un marcador de posición representa un filtro que puede agregar a la regla y que puede ser útil para las tareas de generación de perfiles. Es posible asignar valor a un marcador de posición mientras se configura la programación del KPI (este procedimiento se examinará más a fondo en el párrafo "Creación de documentos"). La sintaxis que se debe usar en las consultas para establecer un marcador de posición es columnName=@placeholderName, como se muestra en el ejemplo de la figura siguiente. + +.. figura:: media/image123.png + + Setting placeholder in query definition. + +Generalmente, la regla de dicha consulta puede devolver una o más medidas y posiblemente un atributo. A continuación se da un ejemplo. + +.. figura:: media/image124.png + + Query definition. + +Se puede asignar una tipología (medida, atributo y atributo temporal) y una categoría a cada campo devuelto por la consulta utilizando el **Metadatos** como se resalta en la siguiente figura. La tipología es necesaria para asociar un tipo a cada campo devuelto por la consulta. En particular, si el campo es temporal, es obligatorio especificar a qué nivel desea que se considere, es decir, si corresponde a un día, un mes, un año, un siglo o un milenio. Para las medidas y atributos es posible asignar también una categoría para buscarlos fácilmente en un segundo momento. + +.. \_metadatasettings: +.. figura:: media/image125.png + + Metadata settings. + +Decimos de antemano que, es importante distinguir estas categorías metedata del campo requerido "Categoría" que se produce al guardar la definición de KPI (ver siguiente figura). + +.. \_kpidefinitioncat: +.. figura:: media/image161.png + + Category assigned when saving a KPI definition. + +De hecho, la categoría asignada al guardar la definición de KPI se agregará (si no existe) en la lista "Categorías de KPI", utilizada para perfilar KPI en roles (consulte la Figura a continuación). + +.. \_kpicategory: +.. figura:: media/image126.png + + KPI category. + +.. advertencia:: +**No confundir la categoría de metadatos con la categoría KPI** + + The category defined in the metadata tab of the "Measure definition" functionally are not the same categories selected in the tab area of the "Roles management" functionality (see the figure above). The first are used to classify the metadata while the second are needed for the profiling issue. + +Como dijimos, existe una categorización adecuada para las agregaciones de tipo temporal. De hecho, al asociar "atributo temporal" como tipología de metadatos, el usuario técnico debe indicar el nivel jerárquico de los datos: día, mes o año. Puede ver un ejemplo en la siguiente figura. Tenga en cuenta que el campo establecido como tipo temporal debe contener números (por lo tanto, no se permiten los tipos de cadena). Por ejemplo, si se desea establecer un campo como "mes", dicho campo debe contener {01,02,03,...,12} que se considerará como {enero, febrero, marzo,...,diciembre}. + +.. \_hierarchyleveltempattrib: +.. figura:: media/image127.png + + Hierarchy level for temporal attributes. + +El **Vista previa** le permite comprobar la ejecución de la consulta y echar un vistazo a una parte del conjunto de resultados. + +Examinemos ahora las características adicionales disponibles en la esquina superior derecha. Allí puedes encontrar la siguiente pestaña: + +* **Elías**: puede ver los alias definidos en otras reglas; tenga en cuenta que solo se almacenan y muestran los alias de esos colums guardados como atributo. Esto es útil para evitar alias ya en uso al definir una nueva regla. De hecho, un alias no se puede guardar dos veces, incluso si está contenido en reglas diferentes. + +.. figura:: media/image128.png + + Checking aliases. + +* **Marcador**: aquí puede consultar los marcadores de posición existentes. Estos se establecen en la consulta que está editando o en otras. + +.. figura:: media/image42930.png + + Setting placeholders in a query. + +* **Salvar**: para guardar la consulta y otros ajustes recién configurados. +* **Cerrar**: para salir de la ventana de configuración de la regla. + +**Definición de KPI.** Seleccione el botón **Definición de KPI** del menú contextual de la página principal de Knowage, como se muestra en la figura siguiente. Haga clic en el icono "Más" para configurar un nuevo KPI. + +.. figura:: media/image131.png + + Configure a new KPI. + +La ventana abre una primera etiqueta, titulada **Fórmula** (consulte la figura a continuación), donde debe escribir la fórmula para habilitar los cálculos. + +.. figura:: media/image132.png + + Formula definition tab. + +Presione la tecla CTRL y la barra espaciadora simultáneamente para acceder a todas las medidas definidas en las reglas, como se muestra a continuación. + +.. \_pressctrlspacemeasure: +.. figura:: media/image133.png + + Press crtl and space to get measures. + +Una vez que se selecciona una medida, debe elegir qué función debe actuar sobre ella. Esto se puede hacer haciendo clic en el botón *f*\ () que rodea a la medida elegida. Vea la figura a continuación. + +.. \_formulasyntax: +.. figura:: media/image134.png + + Formula syntax. + +Haciendo clic en el botón *f*\ () la interfaz abre una ventana emergente donde puede seleccionar qué función se aplica a la medida, consulte la figura a continuación. Una vez realizada la selección, la fórmula se rellenará automáticamente con la sintax adecuada y podrás seguir editándola. + +.. figura:: media/image135.png + + Available functions. + +Una vez que se ha insertado una fórmula completa (un ejemplo se da en la figura a continuación), puede pasar a la siguiente pestaña. + +.. figura:: media/image136.png + +Ejemplo completo de fórmula. + +El **Cardinalidad** le permite definir el nivel de granularidad (es decir, el nivel de agrupación) para los atributos de las medidas definidas. + +Refiriéndose al siguiente ejemplo, seleccionando (con una comprobación) ambas medidas para el atributo product_name, las medidas de KPI se calculan, agrupadas en cada product_name; de lo contrario, no se realizará ninguna agrupación. + +.. figura:: media/image137.png + + Cardinality settings example. + +Los valores límite se pueden establecer mediante la ficha Umbral (figura a continuación). Es obligatorio establecer al menos un umbral, de lo contrario no se puede guardar el KPI. Puede elegir un umbral ya definido haciendo clic en la lista "Umbral" o crear uno nuevo. + +.. figura:: media/image138.png + + Setting thresholds. + +Para insertar un nuevo umbral es obligatorio insertar un nombre y asignar un tipo, mientras que la descripción es opcional. Haciendo clic en **Agregar nuevo umbral** elemento aparece un nuevo elemento. Es necesario definir el **Posición**, **Etiqueta**, **Mínimo** y **Máximo** valores. Es posible elegir si incluir los valores mínimo y máximo en la ranura de valores. El **Severidad** se utiliza para vincular los colores a su significado y hacer que los umbrales sean legibles por otros usuarios técnicos. Tenga en cuenta que el color se puede definir a través del código RGB, el código hexadecimal o eligiéndolo desde el panel. + +Recuerde guardar una vez que se hayan establecido todos los umbrales. + +.. advertencia:: +**Colores "estándar" para umbrales** + + Well call **standard colors** for thresholds the ones listed below (in terms of hexadecimals): + + - green: #00FF00, + - yellow: #FFF00, + - red: #FF0000. + +Finalmente el usuario debe guardar la definición de KPI haciendo clic en el botón "Guardar", disponible en la esquina superior derecha de la página. Una vez que el usuario hace clic en el botón "Guardar", se abre el asistente "Agregar asociaciones de KPI", como puede ver en la siguiente figura. Aquí, es obligatorio asignar un nombre al KPI. Además, el usuario puede establecer la categoría KPI para que solo los usuarios cuyos roles tienen las permmisiones a esta categoría específica puedan acceder al KPI. Recuerde que es posible asignar permisos sobre KPI al definir roles utilizando la funcionalidad "Administración de roles" disponible en la página principal de Knowage. Además, el usuario puede marcar o desmarcar el botón "\ **Habilitar el control de versiones**\ " si desea realizar un seguimiento de las reglas/medidas/objetivos que generan la respuesta de KPI en cada ejecución de KPI. + +.. \_savekpidefcategory: +.. figura:: media/image139.png + + Save the KPI definition and set category. + +**Blanco.** Este paso no es obligatorio. Introduzca el **Definición del objetivo** como se muestra a continuación. + +.. figura:: media/image140.png + + Target Definition menu item. + +Al hacer clic en el icono "Más" puede agregar un nuevo objetivo (Figura a continuación). + +.. figura:: media/image141.png + + Add a new target. + +La definición de un nuevo destino requiere escribir un nombre, una fecha de inicio/fecha de finalización de validez y la asociación a al menos un destino. Es posible asociar un objetivo haciendo clic en el elemento **Agregar KPI** y seleccionando el KPI de interés. Una vez establecida la asociación, el cuadro "Valor" se vuelve editable y puede insertar el valor que desea enviar al KPI seleccionado. Un ejemplo se da en la figura a continuación. + +.. \_kpitargetassoc: +.. figura:: media/image142.png + + KPI target association. + +En la fase de visualización de KPI, se mostrará un grosor en negrita roja en el valor indicado (consulte la siguiente figura). + +.. \_targetmarkkpiscale: +.. figura:: media/image143.png + + Target mark in KPI scale of values. + +Tenga en cuenta que una vez establecidos los objetivos, la ventana de la figura 7.20 se rellena con una lista. Tenga en cuenta que aquí la categoría sirve como descripción y solo para ordenar los registros. + +**Schedulation.** Una vez definidos los KPI, es necesario programarlos para proceder a la creación de un documento analítico. Para este propósito, haga clic en el botón **Programador de KPI** desde el menú contextual que puedes ver a continuación. + +.. figura:: media/image144.png + + KPI Scheduler menu item. + +En cuanto a las otras interfaces, basta con hacer clic en el icono "Plus" para crear una nueva programación. La nueva ventana de schedulation presenta varias pestañas. + +* **KPI**: es posible asociar uno o más KPI a la schedulation haciendo clic en "Agregar asociación de KPI". + +.. figura:: media/image145.png + + KPI tab window. + +* **Filtros**: aquí se asignan valores a los filtros (si están configurados) asociados a la programación. Tenga en cuenta que es posible asignar valores a los filtros mediante una LOV, una lista fija de valores o una función temporal. En caso de que se elija la opción LOV, recuerde que la LOV debe devolver un valor único. Esta opción puede ser útil para las tareas de generación de perfiles. + +.. figura:: media/image146.png + + Filters options. + +* **Frecuencia**: aquí está el lugar donde el intervalo de tiempo de schedulation (fecha de inicio y finalización) se puede establecer junto con su frecuencia. + +.. figura:: media/image147.png + + Frequency tab window. + +* **Ejecutar**: aquí puede seleccionar el tipo de ejecución. Las opciones disponibles distinguen entre el almacenamiento y la eliminación de datos registrados antiguos. De hecho, seleccionando **Insertar y actualizar** el programador calcula los valores de KPI actuales (de acuerdo con la elección de frecuencia) y los almacena en tablas adecuadas sin eliminar las mediciones antiguas y todos los archivos de texto de registro de errores están disponibles justo debajo. Al seleccionar **Eliminar e insertar** se eliminan los datos anteriores. + +.. figura:: media/image148.png + + Execute tab window. + +En la siguiente figura resumimos el caso de ejemplo al que nos hemos referido desde ahora. + +.. figura:: media/image149.png + + Overview of the KPI case. + +Una vez que se completa la programación, haga clic en el botón "Guardar". Recuerde dar un nombre a la schedulation como en la siguiente figura. + +.. figura:: media/image150.png + + Creation of a KPI Document. + +## Creación de un documento KPI + +**Creación de documentos.** Ahora se ha establecido la programación y es posible visualizar los resultados. Necesitamos en este punto crear un nuevo documento analítico de tipo KPI y que utilice el motor KPI (Figura a continuación). Entonces ahorramos. + +.. figura:: media/image151.png + + Overview of the KPI case. + +Haga clic en el botón **Compilación de plantillas** para desarrollar la plantilla. Aquí puede elegir entre KPI y Scorecard (consulte el Capítulo de Scorecard para obtener detalles sobre la opción Scorecard). En el caso de KPI es posible elegir entre los dos siguientes tipos de documento. + +* **Lista**: con esta opción es posible añadir varios KPI que se mostrarán en la misma página con una visualización por defecto. +* **Widget**: con esta opción siempre es posible añadir varios KPI que se mostrarán en la misma página pero en este caso también se le pedirá que seleccione su visualización: Velocímetro o Tarjeta KPI; a continuación, el valor mínimo y el valor máximo que puede asumir el KPI y si desea agregar un prefijo o un sufijo (por ejemplo, la unidad de medida del valor) al valor mostrado. + +Luego, prácticamente debe agregar la asociación de KPI utilizando el área Lista de KPI de la interfaz. Como puede ver en la figura a continuación, puede seleccionar el KPI después de hacer clic en el enlace "AGREGAR ASOCIACIÓN DE KPI". Este último abre un asistente que permite recoger una opción múltiple de los KPI. Una vez elegido, debe especificar todos los campos vacíos del formulario, como "Categoría", "Ver como", etc. (consulte la figura a continuación). Tenga en cuenta que el campo "Ver como" es donde puede decidir si el widget será un velocímetro o una tarjeta KPI. + +.. figura:: media/image152.png + + Setting the KPI associations using the dedicated area. + +Además, puede establecer las otras propiedades del documento KPI utilizando el **Opciones** y el **Estilo** áreas (Figura abajo). + +.. figura:: media/image153.png + + Areas of the Template Build for KPI. + +En particular, es posible dirigir la granularidad de tiempo utilizada por el motor KPI para mejorar los rendimientos. Para ello, en el área "Opciones" (siguiente figura) se invita al usuario a indicar el nivel de agregación eligiendo entre "día", "semana", "mes", "trimestre", "año". + +.. figura:: media/image154.png + + Choose the time granularity. + +Finalmente en el área "Estilo" el usuario puede personalizar el tamaño del widget, la fuente, el color y el tamaño de los textos. + +.. figura:: media/image155.png + + Style settings. + +A continuación, guarde y ejecute el documento. Los ejemplos se muestran en las últimas tres figuras a continuación. + +En caso de que el documento contenga KPI que implique agrupar funciones en algunos atributos, es posible filtrar los datos devueltos en esos atributos. Para recuperar fácilmente los atributos en los que se agrupan las medidas, basta con comprobar los campos enumerados en la pestaña "Cardinalidad" de la definición de KPI. Lo recordamos en la imagen de abajo. + +.. figura:: media/image137.png + + Cardinality settings example. + +Luego, para usarlos para filtrar el documento, primero agregue los controladores analíticos adecuados. Consulte la Sección 5.4 para obtener más información sobre cómo asociar un controlador analítico a un documento (y, por lo tanto, a un documento KPI). Entonces es obligatorio que la URL del controlador analítico *mosto* coinciden con el *alias de atributo* en el que se ha definido la agrupación. + +.. \_kpiassociation: +.. figura:: media/image156.png + + KPI association. + +.. \_widgetdocument: +.. figura:: media/image157.png + + Widget document. + +.. \_kpispeedometer: +.. figura:: media/image158.png + + KPI Speedometer. + +.. \_kpicard: +.. figura:: media/image159.png + + KPI Card. + +.. \_kkpilist: +.. figura:: media/image160.png + + KPI List. diff --git a/functionalities-guide/location-intelligence/index.es.rst b/functionalities-guide/location-intelligence/index.es.rst new file mode 100644 index 00000000..e33aea78 --- /dev/null +++ b/functionalities-guide/location-intelligence/index.es.rst @@ -0,0 +1,396 @@ +# Inteligencia de ubicación + +La inteligencia de ubicación se basa en la idea de que los espacios geográficos son una dimensión analítica particular en el dominio de BI. Se basa en: + +* la representación geográfica de los datos, +* interacción con sistemas SIG, +* datos espaciales, +* operadores espaciales. + +Location Intelligence suele garantizar: + +* una percepción inmediata de la distribución de un fenómeno en una zona geográfica, +* interactividad +* análisis multivariante, +* instantáneas temporales. + +La inteligencia de ubicación se está utilizando ampliamente, principalmente gracias a la aparición de servicios de ubicación como Google Maps. Este dominio es muy fácil de usar para todo tipo de usuarios, generalmente analistas y perfiles operativos. Por el contrario, su gestión no es tan fácil, sobre todo si implica una gestión interna de la base de datos geográficos. + +## Conceptos básicos + +El término Location Intelligence se refiere a todos aquellos procesos, tecnologías, aplicaciones y prácticas capaces de unir datos espaciales con datos empresariales, con el fin de obtener información crítica, apoyar mejor los procesos de toma de decisiones y optimizar las actividades comerciales. + +A nivel tecnológico, esta correlación es el resultado de la integración entre los sistemas de software que gestionan estos dos tipos heterogéneos de datos: los sistemas de información geográfica (SIG), que gestionan datos espaciales, y los sistemas de Business Intelligence (BI), que gestionan los datos empresariales. Esta integración da lugar a nuevas herramientas tecnológicas que apoyan los procesos de toma de decisiones, y el análisis sobre aquellos datos de negocio que están directa o indirectamente relacionados con una dimensión geográfica. + +Las aplicaciones de Location Intelligence mejoran significativamente la calidad del análisis de los usuarios en función de una dimensión geográfica. De hecho, un data warehouse (DWH) casi siempre incluía dicha información. Al representar la distribución geográfica de una o más medidas comerciales en mapas temáticos interactivos, los usuarios pueden identificar rápidamente patrones, tendencias o áreas críticas, con una efectividad que sería inviable utilizando herramientas analíticas tradicionales. + +## Más información sobre SIG y datos espaciales\* + +Datos espaciales + +``` + +The term *spatial data* refers to any kind of information that can be placed in a real or virtual geometric space. In particular, if the spatial data is located in a real geometric space — which is a geometric space that models the real space — it can be defined as *geo-referenced* data. + +.. figure:: media/image374.png + + A base layer in raster and vector format. + +Spatial data are represented through graphical objects called maps. Maps are a portrayal of geographic information as a digital image file suitable for display on a computer screen. + +According to the *Open Geospatial Consortium* (OGC) definition, a map is made of overlapping *layers*: a *base layer* in raster format (e.g. satellite photo) is integrated with other layers (*overlays*) in vector format. Each overlay is made of homogeneous spatial information, which models a same category of objects, called *features*. + +A feature is called *geographic feature* when the constituting objects are abstractions of real-world physical objects and can be located univocally within a referencez coordinate system, according to their relative position. + +.. figure:: media/image375.png + + Overlapping layer. + +A feature includes: + +- a set of attributes that describes its geometry (vector encoding). Geometric attributes must describe its relative shape and position in an unambiguous way, so that the feature can be properly drawn and located on the map, according to the other features of the layers. +- a set of generic attributes related to the particular type of physical object to be modeled. Generic attributes are not defined: they vary according to the type of abstraction that users want to give to each real-world physical object. + +.. figure:: media/image376.png + + Examples of feature. + +There is a wide range of standards that can be used for the vector encoding of spatial data (e.g. GeoJSON, GML, Shape File, etc.). Most geographic information systems can perform the needed conversions among various encodings. + +GIS +~~~ + +Geographic Information Systems (GIS) provide a set of software tools designed to capture, store, extract, transform and display spatial data. Therefore, the term GIS refers a set of sole technological components that manage the spatial data during its whole life cycle, starting from the capture of the data up to its representation and re-distribution. + +From a logical point of view, the key functionalities of a GIS do not differ from those of a BI system. Both systems are characterized by some specific components supporting the effective storage of data, some others supporting their manipulation, their re-distribution or their visualization. On the other hand, the implementation of these functionalities deeply differs between GIS and BI systems, since they deal with two different types of data (alphanumeric and spatial data). + +.. figure:: media/image377.png + + Definition of GIS, BI, spatial data and business data. + +Unlike the market of BI suites, the market of GIS is characterized by a wide spread of open standards, adopted by all main vendors, which regulate the interaction among the various components of the system at all architectural levels. + +.. note:: + **Open Gesospatial Consortium (OGC)** + + The most important International organization for standardization in the GIS domain is the Open Geospatial Consortium (OGC), involving 370 commercial, governmental, non-profit and research organizations. Read more at `www.opengeospatial.org. `__ + + +As for the integration between GIS and BI systems, the OGC has defined two main standards supporting the re-distribution of the spatial data: + +- the *Web Map Service* (WMS). It describes the interface of services that allow to generate maps in a dynamic way, using the spatial data contained in a GIS. +- the *Web Feature Service* (WFS). It describes the interface of services that allow to query a GIS, in order to get the geographic features in a format that allows their transformation and/or spatial analysis (e.g. GML, GeoJson, etc.). + +.. note:: + **WMS and WFS standards for spatial data distribution** + + Full documentation about the WMS and WFS standards can be found at `www.opengeospatial.org/standards/wms `__ and `www.opengeospatial.org/standards/wfs. `__ + +Knowage suite offers an engine supporting the Location Intelligence analytical area, the **GEOReport Engine**, generating thematic maps. + +Analytical document execution +---------------------------------- + +Let’s have a look on the user interface of Knowage Location Intelligence features. + +In Figure belowwe provide an example of a BI analysis carried out thanks to map. In our example, the colour intensity of each state shown proportionally increases according to the value of the indicator selected. States who have no record connected are not coloured at all. + +.. figure:: media/image352.png + + Example of GIS document. USA sales per store + +Click on the arrow on the top right to open the Location Inteligence options panel. Here you can choose the **Map Type**, the indicators to be displayed on the map and you can enter filters. + +.. figure:: media/image35354.png + + Arrow button (left) Location Inteligence options panel (right) . + +The **Map Type** available are: + +- **Map Zone**: the different map zone are filled with different colour range according to the indicator values +- **Map Point**: the indicator values are displayed by points with differs on the radius. A bigger radius means a higher indicator’s value. +- **Map Chart**: thanks to this visualization type you can compare more than one indicators simultaneously. Choose which indicators compare among the available ones. You have to mark them in the **indicator** panel area to visualize them. The charts appears on the map displaying the selected indicators’ values. + +These three typologies of data visualization on map are compared below. + +.. figure:: media/image3555657.png + + Map Zone (left) Map Point (center) and Map Chart (right). + +Now you can add extra layers on the default one. Switch to the **layer** tab of the Location Inteligence options panel. + +Here click on **select form catalog**, choose the layers you want to add. Mark them in the bottom part of the Location Intelligence area in the Layer box and the selected layer are displayed. These steps are shown in figure below. + +.. _stepsforlayeradd: +.. figure:: media/image358.png + + Steps for layer adding + +In our example we upload some waypoints, you can see the results obtained in next figure. + +.. _mapwithlayers: +.. figure:: media/image359.png + + Map with two layers + +Now let’s focus on **Configuration** tab of Location Inteligence panel option. Here you can set some extra configurations. Let’s have a look them for each data visualization typology. + +For the **Map Zone** you can set: + +- **Method**: the available ones are quantiles or equal intervals. If you choose quantiles data are classified into a certain number of classes with an equal number of units in each classe. If you choose equal Intervals the value are divided in ranges for each classe, the classes are equal in size and their number can be set. The entire range of data values (max - min) is divided equally into however many classes have been chosen. +- **N°of classes**: the number of intervals in which data are subdivided. +- **Range colours**: You can choose the first and the last colour of the range. For both of them you can use a colour pixer by clicking on the coloured square. An example is provided below. + +.. figure:: media/image360.png + + Map Zone extra configurations + +For the **Map Point** you can set: + +- **Colour**: the colour of the circle. +- **Min/Max value**: the minimum and the maximum circles radius. + +For the **Map Chart** you can set the colour of each chart’s bar. + +The last tab of the panel is dedicate to the template preview, it is provided for advanced user who want to have an approach on generated code. + +We can conclude our overview on GIS document describing the buttons located at the bottom right corner, you can see them underlined in the following figure. From the left to the right this bottons can be used for: have a look at the legend, compute a measure of an area of the map and do the .pdf export of the map. + +.. _legendmeasurexport: +.. figure:: media/image361.png + + From the left to the right: Legend, Measure and Export bottom. + +Extra functionalities +``` + +Volvamos a la pestaña principal de la capa de ubicación y nos centramos en el **Seleccionar modo** área. Si se ha configurado la navegación cruzada, encontrará dos opciones: **identificar** y **Navegación cruzada**. + +Escoger **Navegación cruzada**el **Elemento espacial** aparece la pestaña. En esta pestaña puede configurar su selección. Para hacer su selección, oculte la tecla CTRL y elija el área en el mapa con el mouse. Si eliges **cerca**, se seleccionan las características del conjunto Km. Si eliges **cruzar**, las características cuyos bordes se cruzan con el área diseñada. Si eliges **adentro**, solo las características completamente dentro de su área de selección se consideran para la navegación cruzada. + +Cuando se realiza la selección, aparece un cuadro. En este cuadro encontrará información de navegación cruzada. El número de entidades seleccionadas y un botton para realizar la navegación cruzada con la selección activa. + +## Creación de plantillas con el diseñador SIG + +Las plantillas de documentos del motor SIG ahora se pueden crear utilizando el diseñador SIG. El Diseñador está disponible en la página de detalles del documento del administrador (para esta parte, consulte la Sección 15.8) y también para el espacio de trabajo de los usuarios finales. El proceso de creación y las secciones del diseñador se describen en el texto a continuación. + +Un usuario final puede crear un documento SIG desde el área de trabajo de Knowage Server. Siga My Workspace » Análisis y haga clic en el icono "Plus" disponible en la esquina superior derecha de la página e inicie un nuevo **Análisis georreferenciado**. + +.. figura:: media/image362.png + + Start a new Geo-referenced analysis. + +Cuando se abre el diseñador, existe la opción de elegir el conjunto de datos para unir datos espaciales y datos profesionales. Cuando se selecciona el conjunto de datos, aparecerán las secciones Columnas e indicadores de unión de conjuntos de datos. De forma predeterminada, el conjunto de datos no está elegido y hay una interfaz para crear un mapa sin datos profesionales + +.. figura:: media/image363.png + + GIS document designer window. + +## Secciones de diseño + +Sección de capa + +``` + +Definition of the target layer is configurable in layer section. If the dataset is selected one of the available layers is chosen from list of layers catalogs. Button change layer (next figure) opens a pop up with a list of all available layer catalogs. Selecting one item from the list and clicking save the selected item will be chosen for template. + +.. _targetlayerdef: +.. figure:: media/image364.png + + Target layer definition. + +.. _listavailbcatalog: +.. figure:: media/image365.png + + List of available layer catalogs. + +In case when there is no dataset multiple layers can be selected below. + +.. figure:: media/image366.png + + Multiple selection of available layers. + +Dataset join columns +``` + +La sección columnas de unión al conjunto de datos es para configurar la unión de datos espaciales y datos profesionales. Esta sección solo está presente cuando se selecciona el conjunto de datos para el documento. La estructura de datos del diseñador para unirse está representada por los pares de columnas de dataset y columnas de capa correspondientes. Al hacer clic en agregar columna de unión que puede ver en la figura debajo aparece un nuevo par vacío. La columna de unión al conjunto de datos se puede seleccionar entre las columnas del conjunto de datos seleccionado eligiendo una opción del cuadro combinado. La columna de unión de capas debe agregarse como texto libre editando la columna de tabla correspondiente. + +.. figura:: media/image367.png + + Dataset join columns interface. + +Indicadores + +``` + +Measures definition is configurable by adding indicators. The interface is shown below. This section is only present when dataset is chosen for the document. Indicators are represented by pairs of measure field from selected dataset and corresponding label that will be used on map. Clicking on add indicators creates empty pair. Measure filed should be selected by picking one option from combo box that contains measure fields from selected dataset. Label should be inserted as free text by editing corresponding table column. + +.. _indicatorsinterface: +.. figure:: media/image368.png + + Indicators interface. + +Filters +~~~~~~~ + +Using the filtering dedicated area, as ahown in figure below, you define which dataset attributes can be used to filter the geometry. Each filter element is defined by an array (e.g. name : "store_country", label:"COUNTRY"). The first value (name : "store_country") is the name of the attribute as it is displayed among the properties. The second one label: "COUNTRY" is the label which will be displayed to the user. This section is only present when dataset is chosen for the document. Clicking on add filter creates empty pair. Label field should be selected by picking one option from combobox that contains attribute fields from selected dataset. Label should be inserted as free text by editing corresponding table column. + +.. _filtersinterfac: +.. figure:: media/image369.png + + Filters interface. + +Map menu configuration +``` + +A través de la **Configuración del menú Mapa** Panel que el usuario puede desactivar para habilitar o deshabilitar algunas funciones y características disponibles, como la leyenda, la calculadora de distancia, etc. Vea la siguiente figura para echar un vistazo a los elementos disponibles. + +.. \_mapmenuconfig: +.. figura:: media/image369.png + + Map menu configuration. + +Filtros de capa + +``` + +Here, as you can see from figure below, you define which target layer attributes can be used to filter the geometry. This section is only present when a dataset has been selected. Add filters button opens pop up where you can choose all available filters of the selected layers. Figure below gives an example. + +.. figure:: media/image370.png + + Layer filters interface. + +.. figure:: media/image371.png + + List of available filters. + +Edit map +~~~~~~~~ + +When all required fields are filled basic template can be saved. From workspace user is first asked to enter name and description of new created document as in the following figure. When the template is saved successfuly EDIT MAP button is enabled in the right part of the main toolbar. + +.. figure:: media/image372.png + + interface for name and description of new geo document for end user. + +Clicking the edit map button will open created map. An example is given below. In edit mode you are able to save all custom setting made on map. + +.. figure:: media/image373.png + + Map in edit mode with save template available. + +GEOReport Engine\* +----------------------- + +The **GEOReport Engine** implements a *bridge integration* architecture. + +Generally speaking, a bridge integration involves both the BI and the GIS systems, still keeping them completely separated. The integration between spatial data and business data is performed by a dedicated application that acts as a *bridge* between the GIS and the BI suite. This application extracts the spatial data from the GIS system and the business data from the BI suite, to answer the users’ requests. Afterwards, it joins them and provides the desired results. + +In particular, the **GEOReport Engine** extracts spatial data from an external GIS system and join them dynamically with the business data extracted from the Data Ware House, in order to produce a thematic map, according to the user’s request. In other words, it acts as a *bridge* between the two systems, which can consequently be kept totally decoupled. + +.. figure:: media/image378.png + + Bridge integration architecture of the **GEOReport Engine**. + +The thematic map is composed of different overlapping layers that can be uploaded from various GIS engines at the same time. Among them just one layer is used to produce the effective thematization of the map: this is called *target layer*. + +You can manage your layers inside the **Layers Catalogue**. + +Here you can upload the following layer types: + +- File; +- WFS; +- WMS; +- TMS; +- Google; +- OSM. + +Create a new layer clicking on the dedicated plus icon. On the right side you are asked to fill few settings before saving the new layer. Among these settings the firsts are equals for all types of layers. Once you choose the layer type, instead, some fields may change. This happens to manage all layers types from the same interface. For example if you choose **File** as type you have the possibility to chose your own .json file and upload it. After having done this, the path where your file is been uploaded is shown among the setting. + +If you chose **WFS** or **WMS** you are asked to insert a specific url. + +At the bottom part of layer configuration you can manage the layer visibility. Mark the role you want to give visibility previlegies on this layer. If none is marked, the layer is visibile to all role by default. + +Once you have set all layer configuration you can switch to filter setting. Click on the tab you can find in the upper part of the screen, see the following figure. + +.. figure:: media/image379.png + + Filter tab + +Here you can choose which filters will be active during visualization phase. Choose among the properties of your layer, the available ones are only the string type. + +Now you need to have a well-configured dataset to work with the base layer. The dataset has to contain one column matching a property field as type and contents otherwise you will not be able to correctly visualize your data on the map. + +For example you can use a query dataset, connected to the foodmart data source, whose SQL query is shown in Code15.1. + +.. code-block:: sql + :caption: GeojSON file except. + :linenos: + + SELECT r.region_id as region_id + , s.store_country + , r.sales_state as sales_state + , r.sales_region + , s.store_city + , sum(f.store_sales) + (CAST(RAND() \*60 AS UNSIGNED) + 1) store_sales + , avg (f.unit_sales)+(CAST(RAND()\* 60 AS UNSIGNED) + 1) unit_sales + , sum(f. store_cost) store_cost + FROM sales_fact_1998 f + , store s + , time_by_day t + , sales_region r + WHERE s.store_id=f.store_id + AND f.time_id=t.time_id + AND s.region_id = r.region_id + AND STORE_COUNTRY = 'USA' + GROUP BY region_id, s.store_country,r.sales_state, r.sales_region, s.store_city + + +Create and save the dataset you want to use and go on preparing the document template. + +Template building with GIS designer for technical user\* +---------------------------------------------------------- + +When creating new location intelligence document using GIS engine basic template can be build using GIS designer interface. For administrator designer opens from document detail page clicking on build template button (refer to next figure). When the designer is opened the interface for basic template build is different depending on if the dataset is chosen for the document or not. + +.. _gisdesigneraccestemplbuild: +.. figure:: media/image381.png + + Gis designer accessible from the template build. + +We have already described the Gis Designer when it is accessed by a final user. Since the difference relies only in how the designer is launched we will not repeat the component part and recall to *Designer section* paragraph for getting details. By the way we highlight that there is a last slight difference when defining a filter on layers. In fact, using the administrator interface, if the document has analytical driver parameters, you can also choose one of the available parameters to filter the geometry, as shown below. It is not mandatory to choose layer filters so you can also save the template without any filter selected. + +.. _layerfiltranalytdriv: +.. figure:: media/image382.png + + Layer filters interface with analytical drivers. + +When the list of selected layers is changed the filter list will be empty so you have to select filter list after filling the layer list, this is the way designer keeps consistency between layers and corresponding filters (see next figure). + +.. _listavailfiltranalydriv: +.. figure:: media/image383.png + + List of available filters with list of analytical drivers. + +Cross navigation definition\* +----------------------------------- + +It is possible to enable cross navigation from a map document to other Knowage documents. This means that, for instance, clicking on the state of Texas will open a new datail documents with additional information relative to the selected state. + +You need to define the output parameters as described in Section *Cross Navigation* of *Analytical Document* Chapter. The possible parameters that can be handled by the GIS documents are the attribute names of the geometries of layers. + +Once you have created a new Cross Navigation in the Cross Navigation Definition menu in Tools section, it is possibile to navigate from the GIS document to a target document. There is still a little step to do to activate the cross navigation. + +.. figure:: media/image384.png + + Cross navigation option. + +Open the **layer** tab of the Location Intelligence options panel and click on cross navigation select mode. Now the cross navigation is activated and if you click, for example, on one of the state it will compare the above popup. + +.. figure:: media/image385.png + + Cross navigation popup. + +By clicking on the play button the target document will open. + +``` diff --git a/functionalities-guide/meta-web/index.es.rst b/functionalities-guide/meta-web/index.es.rst new file mode 100644 index 00000000..1a99101b --- /dev/null +++ b/functionalities-guide/meta-web/index.es.rst @@ -0,0 +1,365 @@ +# Meta Web + +En este capítulo entramos en detalles de cómo construir tu propio metamodelo. Knowage permite desarrollar y gestionar metadatos mediante el uso de una interfaz web que se denomina **Meta Web**. Recordamos que tratar con metadatos significa administrar datos que describen la estructura de un modelo relacional, es decir, tratar la relación entre tablas, columnas de tabla, claves, etc. + +La Meta Web permite al usuario acceder a esta información mediante el uso de una interfaz gráfica y combinarlas, redefinirlas y consultarlas fácilmente en un modelo abstracto, garantizando la seguridad del modelo fuente. Además, hacemos hincapié en que los usuarios pueden realizar consultas sobre datos sin el uso de un lenguaje de consulta de datos. + +## Creación de metamodelos + +Utilizando la aplicación Meta Web, es posible invertir el contenido de una base de datos y manipular esta información creando un nuevo modelo que pueda ajustarse a las necesidades del usuario. En este apartado veremos cuáles son los pasos necesarios para crear un metamodelo y consultarlo con el QBE. + +Para crear un metamodelo, escriba el **Catálogo de Modelos de Negocio** y agregue un nuevo modelo haciendo clic en el icono "Plus". En relación con la siguiente figura, se le pedirá que introduzca los siguientes campos: + +* Nombre (obligatorio): Nombre del modelo (no se puede cambiar después del guardado). +* Descripción: una descripción más larga del modelo. +* Categoría (obligatorio): Seleccione, de entre las disponibles, una categoría a la que pertenezca el modelo. +* Origen de datos (obligatorio): seleccione el origen de datos que se utilizará para crear su modelo (es decir, el que contiene las tablas que necesita). + +.. \_settingthemodelinfo: +.. figura:: media/image299.png + + Setting the metamodel basic information. + +Después de haber recopilado esta información, puede usar el botón de navegación para cargar un modelo desarrollado a través de una herramienta externa (y específica) o puede hacer clic en "Guardar" en la esquina superior derecha de la pantalla y usar el motor Meta Web para construirlo a través de la interfaz knowage. Ahora haga clic en el interruptor **Habilitar Meta Web** que mostrará un botón **Meta Web**, haga clic en eso y estará listo para diseñar el modelo. + +## Asociación con conductores analíticos + +La nueva característica en meta web son los controladores analíticos y su conexión al meta modelo a través de filtros. En esta sección mostraremos cómo definir prácticamente esta asociación. + +Para agregar un nuevo parámetro, puede hacer clic en la pestaña **Controladores** y luego en un **Agregar** , vea la siguiente figura. + +.. figura:: media/image299a.png + + Association with analytical driver panel. + +Elija un nombre para el título del conductor. A continuación, elija el controlador analítico en el menú desplegable que desea asociar al metamodelo. + +Una vez que haya seleccionado el controlador, debe escribir el **URL exacta** del parámetro correspondiente. A continuación, establezca si el controlador es multivalor o no. De forma predeterminada, los controladores están configurados para ser obligatorios, por lo que no tiene la opción de cambiar eso como lo tiene para el documento analítico. + +Una vez que haya completado la definición de un parámetro, puede guardarlo haciendo clic en principal **Salvar** en la esquina superior derecha. Para agregar más parámetros, haga clic en el botón **Agregar** botón. Repita el mismo procedimiento tantas veces como desee. En este punto, es posible que desee cambiar el orden de los parámetros (es decir, cómo se presentan al usuario). Para hacerlo, haga clic en la flecha en la lista de controladores. + +.. figura:: media/image299b.png + + Association with analytical driver panel. + +A continuación veremos algunas operaciones especiales que se pueden realizar en drivers asociados a un metamodelo. + +Correlación entre parámetros + +``` + +In the context of a meta model, two different parameters may be connected to each other: this means that the possible values of a parameter are limited by the value(s) of another parameter. + +This feature can be useful when two (or more) parameters are logically related. For example, suppose to have a parameter for all the possible countries and another one for all the possible cities. If the user selects a region, it is meaningless to show him all cities: he should only be enabled to choose among the cities in the selected region. + +To set the correlation, select child parameter which will show you the details of that particular driver and then click on the **Add condition** button to open pop-up window for defining data correlation. + +.. figure:: media/image299c.png + + Adding data correlation. + +In general, to configure a correlation within a meta model you should make sure that the LOV associated with the parent parameter and the one associated to the child parameter share at least one column. This column defines which value from the parent parameter will be applied to the child, in order to constrain the results. + +.. figure:: media/image299d.png + + Definition of the correlation. + +Here you need to define: + +- the parent parameter; + +- the type of logical operator, in order to compare values of the parent parameter with values of the child parameter; + +- the column, generated by the child parameter, whose value will be compared with the value of the same column in the parent parameter. + + +If a parameter depends on multiple parent parameters, you can define multiple correlations. + +.. figure:: media/image299e.png + + Multiple correlations. + +Once defined the correlation, the child parameters will display the labels during the runtime in italics. + +Correlation through LOV and drivers +``` + +En secciones anteriores vimos cómo establecer la correlación a través de la GUI disponible en el panel del meta modelo, pero también existe la posibilidad de obtener el mismo resultado utilizando el enlace entre LOV y los controladores analíticos. Más en profundidad, el usuario debe haber configurado previamente un controlador que ejecute valores que se puedan usar en la cláusula "where" de una consulta SQL. A continuación, el usuario debe establecer un LOV de tipo de consulta mediante la sintaxis + +Destacamos que el `AD_name` es el nombre del controlador al que el administrador intenta llegar. La sintaxis para establecer la correlación a través de la configuración de LOV es: + +.. code-block:: bash +:caption: Sintaxis para establecer la correlación a través de la configuración de LOV +:linenos: + +$P{AD_name} + +.. figura:: media/image82.png + + Correlation passing driver values to LOV query . + +Como resultado, al abrir el metamodelo, tan pronto como el usuario recoja un valor del parámetro "libre", el otro se filtra y mostrará solo el valor relacionado con la selección anterior, como se muestra en la Figura a continuación. + +.. figura:: media/image83.png + + Filtering with correlation. + +Crear un modelo vacío + +``` + +The first time you enter the Meta Web, the interface (see Figure 10.2) will show you the available tables extracted from the selected data source. + +.. figure:: media/image300.png + + Metaweb interface. + +For each table you can decide if you want to include it in your metamodel. More in detail a metamodel is divided in two model: + +- **Physical Model**: it represents a “snapshot” of the database at the moment of the creation of you metamodel. The physical model contains a list of tables and information like columns and foreign keys retrieved from the database. The Physical Model cannot be modified but could be updated to reflect changes made on the database after the creation. + +- **Business Model**: it is based on the physical model but let the user recombine some of his information. For example is possible to create a Business Class that contains only some of the columns of a Physical Table and create new relationships between Business Classes that are not defined on the physical database. + +If you choose to include a table only in the physical model is always possible to create a corresponding business class later during the editing. When you have finished to select the tables you can proceed to the editing clicking on the **Continue** button. + +Editing the metamodel +``` + +El Meta Web Editor se divide en dos pestañas principales **Modelo de Negocio** y **Modelo físico** correspondientes a los modelos relacionados. Al hacer clic en una de estas pestañas, se cambiará la vista que muestra los elementos del modelo específico. + +La pestaña "Modelo físico" contiene las tablas que el usuario ha comprobado anteriormente. En el lado izquierdo de la interfaz verá una estructura similar a un árbol con la lista de tablas importadas en el Modelo físico (consulte la figura a continuación). + +.. figura:: media/image301.png + + Physical Model Tab. + +El icono "similar a un hambuger" permite al usuario actualizar el modelo físico en cualquier momento. En referencia a la siguiente figura, seleccionando la opción "Actualizar modelo físico", el usuario puede actualizar los metadatos del modelo. + +.. \_updtphisicalmdl1: +.. figura:: media/image302a.png + + Update the physical model. + +Como se muestra a continuación, la interfaz muestra si se han agregado o eliminado tablas al origen de datos y permite al usuario agregar tablas al modelo físico. + +.. \_updtphisicalmdl2: +.. figura:: media/image30607.png + + Update the physical model. + +Cada tabla de Modelo Físico trae la información leída de la base de datos. Al seleccionar cada tabla, la interfaz muestra a la derecha la lista de sus propiedades (**Lista de propiedades** tab) y sus claves externas (**Claves externas** pestaña). Haciendo clic en el icono de la izquierda de cada Tabla Física, es posible expandir el nodo correspondiente. Resalte el nombre de cada columna para ver (en el lado derecho de la pantalla) una lista de propiedades, como el tipo de datos o la longitud. + +La pestaña Modelo de negocio, que se muestra a continuación, permite al usuario personalizar el modelo en términos de nombre de columna, tipo, visibilidad, formato, etc. + +.. figura:: media/image308.png + + Physical Model Tab. + +En esta vista, verá toda la clase Business creada en la primera inicialización. Además, las clases de negocios están representadas en una estructura de árbol en el lado izquierdo de la página. Al hacer clic en el nombre de cada clase empresarial, la información genérica se informa en las cinco pestañas disponibles en el lado derecho de la página (Figura a continuación). + +.. figura:: media/image309.png + + Exploring Business Class properties. + + Change the order of the business classes + +Si desea cambiar el orden de las clases de negocios, puede hacerlo utilizando la funcionalidad de arrastrar y soltar. + +.. figura:: media/entityDragDrop.png + +Uso del **Lista de propiedades** , el usuario puede personalizar el nombre de la clase empresarial, escribir una descripción y ver el nombre de la tabla física correspondiente. Aquí el usuario también puede optar por ocultar la clase empresarial configurando su visibilidad en false. Además, al especificar el tipo de clase empresarial, el usuario activa algunas funciones peculiares que se pueden utilizar en la interfaz QbE que describimos en la Sección 9.1. Por ejemplo, al seleccionar la dimensión geográfica, el usuario podrá aplicar las funciones espaciales a los campos de dimensión disponibles en la interfaz QbE. + +El **Atributos** permite al usuario definir qué columnas se utilizarán como claves principales y cuáles son efectivamente funcionales para la clase Business (no confundir con la condición de visibilidad). Tenga en cuenta que, por ejemplo, no es posible deshabilitar la opción "En uso" cuando el campo ya se ha establecido como clave externa. + +El **Campo calculado** se utiliza para configurar medidas o atributos calculados. Haga clic en el botón dedicado, como se muestra a continuación, para crear un nuevo campo. Utilice la lista de funciones para recuperar la sintaxis de la función derecha y la lista de campos de la izquierda para escribir correctamente el nombre de los campos. + +.. figura:: media/image310.png + + Add calculated fields. + +El **Entrantes** y **Salida** las fichas se describen en la siguiente sección. + +Crear una nueva relación + +``` + +In the Business Model is possible to define new relationships between Business Classes that are not inherited from the physical foreign keys. The Business Relationships are divided in two types: + +- **Inbound**: relationships that have the selected Business Class as a target (so they are entering); +- **Outbound**: relationships that have the selected Business Class as a source (so the starts from). + +The two relationships differ then for the direction of the bounds between tables that they establish. + +To create a new relationship, just select the tab “Inbound” or “Outbound” after selecting one Business Class. Then click on the button “Add” and you will see a dialog. + +.. figure:: media/image311.png + + Setting the outbound relationship. + +In Figure above the outbound relationship is shown. Here you have to: + +- enter the business relationship name, +- select the cardinality of the relationship (1 to N is suggested), +- select the Source and Target Business Classes, +- Then is possible to drag and drop a Business attribute from the source Business Class to another Business attribute in the target Business Class. This will create a link between the two attributes. + +When all these steps are accomplished, click on “Create” to save. + +We stress that the cardinality of the outbound relationship can be of two types: + +- 1 to N, +- 1 to N\*. + +Use the second type of cardinality when the type of cardinality can be optional. + +As well, the cardinality of the inbound relationship can be of two types: + +- N to 1, +- N\* to 1. + +Use the second type of cardinality when the type of cardinality can be optional. + +SQL Filter +~~~~~~~~~~ + +There is a new feature that is added in meta web. It is SQL Filter which we can define in Filter tab in meta web as you can see in the figure below. SQL Filter is used for applying already defined drivers in query. + +.. figure:: media/image1.png + +SQL filter is expression that is added in the end of query as part of where clause. The right syntax for sql filter is: +column_name = $P{url_name_of_the_driver}. For example: city = $P{cityUrl}. If you want to add more than one filter, you can connect them with an operator (AND, OR...) as you can see in an example in figure below. + +.. figure:: media/image2.png + +If you want to add filter for multivalue driver the right syntax is this: column_name IN ($P{url_name_of_the_driver}). For example: +city IN ($P{cityUrl}). + + +Create a new business class +``` + +En la pestaña "Modelo de negocio", el icono sándwich permite al usuario agregar otras clases de negocio (desde las tablas del modelo físico) o una vista de negocio (una combinación de más tablas con una ruta de unión predefinida). + +.. figura:: media/image31213.png + + Create a new business class. + +Al hacer clic en el icono, como se muestra en la figura anterior), y seleccionar "Nueva clase de negocio", un nuevo cuadro de diálogo solicita a los usuarios que: + +* seleccionar una tabla física de las disponibles; +* insertar una descripción para esta nueva clase empresarial; +* seleccione una o más columnas. + +Luego haga clic en guardar para agregar la clase ejecutiva. + +Además, al hacer clic en "Nueva vista de negocio", como se informa en la figura a continuación, se le pide al usuario que seleccione dos o más tablas de las disponibles e inserte una descripción para esta nueva vista de negocio. + +.. figura:: media/image31214.png + + Create a new business view. + +Luego, pasando al siguiente paso, el usuario debe unir tablas a través de columnas específicas, normalmente las claves externas de las tablas. La siguiente figura muestra un ejemplo. + +.. figura:: media/image31516.png + + Create a new business view. + +Para cada vista de negocio, la interfaz informa de las mismas fichas de propiedades que vimos para cada clase de negocio. Además, el usuario encuentra el **Unir relaciones** y el **Tabla física** , como se resalta en la siguiente figura. La pestaña "Unir relaciones" muestra las cláusulas de unión establecidas para crear la vista de negocio, mientras que la pestaña "Tabla física" recuerda los nombres de las tablas físicas. + +.. figura:: media/image317.png + + Additional property tabs for business view. + +Lista de propiedades de tabla + +``` + +Scrolling the table “Property list” tab, the user finds the **Type** menu item. Expanding the related combobox the user can custom the table type among the ones available and listed below. + +.. figure:: media/image31819.png + + Table property list. + + +Column property list +``` + +Además, el usuario puede emplear cada lista de propiedades de campo (consulte la siguiente figura) para inspeccionar el objeto y personalizarlo. + +.. \_clmnproprtylist: +.. figura:: media/image322.png + +Lista de propiedades de columna. + +El **Estructural** el área cubre un papel importante para las propiedades del campo. Aquí el usuario puede configurar: + +* **Visibilidad** sobre el campo, +* **Tipo**, entre medida, atributo, calendario, temporal_id, the_date y hour_id, +* **Tipo de agregación** para el tipo de campo de medida, +* **Cadena de formato**, para personalizar el formato de la cadena para el tipo de campo de medida, +* **Atributo de perfil**, para filtrar el campo (y, a continuación, los registros de tabla) por los atributos de perfil de usuario (tenga en cuenta que el cuadro combinado enumera los atributos de perfil disponibles), +* **Tipo de filtro de atributo de perfil**, para definir el operador del filtro entre "igual a", "en", "me gusta", +* **Tipo de dato**, para indicar el tipo de datos de campo. + +En **Modelo de comportamiento** , el usuario puede asignar el permiso de visibilidad del campo a roles específicos. + +En **Físico** área, recuerda la tabla física y el nombre del campo del que se ha tomado el campo. + + Add new column into business class + +Si no eligió todas las columnas de la tabla física, cuando estaba creando una nueva clase de negocios, puede hacerlo fácilmente. Haga clic en la clase ejecutiva en la que desea agregar una nueva columna. Abra la pestaña Atributos y haga clic en el nombre de la columna anterior. + +.. figura:: media/addNewBusinessColumn.png + + Remove existing column from business class + +Si desea eliminar la columna de la tabla de negocios, debe hacer clic en la clase de negocios de la que desea eliminar la columna. Abra la pestaña Atributos y haga clic en tres puntos de la columna que desea eliminar. Se abrirá el panel de detalles. Haga clic en el botón eliminar. + +.. figura:: media/deleteBusinessColumn.png + + Change the order of the columns + +Si desea cambiar el orden de las columnas, puede hacerlo utilizando la funcionalidad de drad y drop. + +.. figura:: media/columnDragDrop.png + +Generar el datamart + +``` + +After the editing of the metamodel, click on “Save” on the Meta Web toolbar on the upper right corner. Now you have a metamodel that can be compiled and used to generate a datamart. Now if you go back to the Business Model catalog you will see that near the “Meta Web” button there is a “Generate” button. Clicking on it, a dialog will open: + +.. figure:: media/image323.png + + Generate datamart dialog. + +If you just press “Create” the generation of the datamart begins otherwise clicking on the switch “Show Advanced options” (see figure below) the user can modify model name, change the schema or the catalogue of the database used to query the metamodel. This option is useful when the user wishes to build the model on a source schema and produce the datamart on a different one. Furthermore, the user can check the **Generate for registry** box. In this instance, the generated datamart will be used as a registry (but will not be exploited as a QbE). The **Include source code** produces a “file.jar” containing both the compiled code (.class) and the source files (.java), useful for the debagging process. + +.. _generdatamdialogadv: +.. figure:: media/image324.png + + Generate datamart dialog: advanced options. + +When the datamart is generated it will be possible to query the metamodel accessing it in the Workspace interface. + +Additional functions for business model +``` + +En esta sección, describimos brevemente las opciones genéricas disponibles para el desarrollo de modelos de negocio. Refiriéndose a la figura a continuación, el usuario primero encuentra el **Modelo de bloqueo**: si está habilitado, solo el usuario que desarrolló el modelo puede modificarlo. + +.. figura:: media/image325.png + + Business model lock. + +Una vez guardado el modelo, se habilitan algunas opciones más. De hecho, el usuario puede aprovechar el **Metadatos** sección. Haciendo clic en el botón **Importar metadatos** , la información de metadatos relacionada con las clases de negocio (su composición, propiedades, etc.) se almacenan en la base de datos (metadatos) Knowage. Esa información se puede visualizar a través de un documento específico (desarrollado para el contexto del linaje de datos). + +.. figura:: media/image326.png + + Importing metadata. + +Finalmente el **Versiones guardadas** el usuario realiza un seguimiento de los cambios del modelo a lo largo del tiempo. Además, es posible restaurar versiones antiguas comprobando la columna activa. Al seleccionar el icono de "tres puntos", el usuario puede descargar el archivo jar o el modelo en sí o eliminar la versión. +La siguiente figura muestra un ejemplo. + +.. figura:: media/image327.png + + Saved version functionalities. diff --git a/functionalities-guide/multidimensional-analysis/index.es.rst b/functionalities-guide/multidimensional-analysis/index.es.rst new file mode 100644 index 00000000..8b85e00d --- /dev/null +++ b/functionalities-guide/multidimensional-analysis/index.es.rst @@ -0,0 +1,1075 @@ +# Análisis multidimensional + +Las herramientas OLAP permiten a los usuarios analizar datos multidimensionales de forma interactiva desde múltiples perspectivas. OLAP consiste en operaciones analíticas básicas: cortar y dar, enrollar, profundizar y pivotar. + +## Manual de usuario de OLAP paso a paso + +Comenzamos nuestra conferencia sobre el motor OLAP analizando un documento OLAP existente. Abra la carpeta del explorador de documentos de la suite Knowage como se muestra a continuación e inicie un documento OLAP. + +.. figura:: media/image134.png + + Browse the documents and select an OLAP document. + +Aquí un ejemplo. + +.. figura:: media/image135.png + + Exploring an existing OLAP document. + +Describiremos las partes principales de la página OLAP a continuación. + +El panel de filtros + +``` + +Once the document is executed, the central area of the window contains the table whose measures are aggregated on dimensions. At the top of this area, panels are available to configure filters on attributes. We see in the following figure that the filter panel is made up of **Filter cards**. Here you can find the cube dimensions and their hierarchies as defined in the OLAP schema by the developer. + +.. figure:: media/image136.png + + The filter panel. + +The filter cards +``` + +Las tarjetas de filtro se pueden colocar en el panel de filtro o en el eje de columna. Puede cambiar su posición arrastrándolos y soltándolos de un lugar a otro. + +.. figura:: media/image137.png + + The filter card inside the filter panel. + +Las tarjetas de filtro se utilizan para: + +* informar al usuario acerca de las dimensiones disponibles definidas en el esquema OLAP, +* informar al usuario sobre el nombre de la dimensión, +* rebanadas de rendimiento, +* Agregue las dimensiones a la visualización del cubo, +* colocar jerarquías en diferentes ejes, +* filtrar miembros visibles. + +Teniendo en cuenta la siguiente figura, podemos ver que una tarjeta de filtro se compone de: + +* un icono para abrir el cuadro de diálogo selector de cotas (a), +* un nombre de dimensión (b), +* segmentación de datos de iconos (c)+(e), +* nombre de filtro elegido (d), + +.. \_featuresoffiltcard: +.. figura:: media/image13839.png + + Features of a filter card. + +Panel Ejes + +``` + +In the panel axes you can: + +- drag and drop one or more dimensions, +- organise the dimensions visualization, +- swap axes. + +Referring to the following figure, the axes panel consists of the following items: + +- columns axis (a), +- row axis (b), +- filter cards (c), +- icon for swap axes (d), +- icon for hierarchy order (e). + +.. _axespanelfeat: +.. figure:: media/image140.png + + Axes panel features. + +Pivot table +``` + +La tabla dinámica es la parte central de la página OLAP. En la siguiente figura se muestra un ejemplo. + +.. figura:: media/image141.png + + Pivot table. + +La tabla dinámica se utiliza para: + +* mostrar datos basados en consultas MDX enviadas desde la interfaz, +* desglose/aumento de las dimensiones de las jerarquías, +* perforar a través de, +* mostrar las propiedades de un miembro en particular, +* ordenar datos, +* mostrar campos calculados, +* realizar la navegación cruzada a otros documentos. + +Refiriéndose a la siguiente figura, la tabla dinámica consta de: + +* dimensiones implicadas en el análisis (a), +* celdas con datos (b), +* iconos para profundizar y profundizar (c), +* iconos para ordenar (solo si el desarrollador lo habilita) (d), +* iconos para mostrar propiedades (solo si el desarrollador habilita y configura) (e), +* enlaces para la navegación cruzada (solo si el desarrollador lo habilita y configura) (f). + +.. \_pivottablefeat: +.. figura:: media/image142a.png + + Pivot table features. + +Barra lateral + +``` + +You can open the side bar by clicking on the icon positioned on the top right side of the page (see next figure). Side bar will be shown on the right side (see *Side bar* figure). + +.. _openthesidebar: +.. figure:: media/image143.png + + Open the side bar. + +Side bar is used to: + +- choose between different data representations, +- choose between different drill types, +- call dialogs and functionalities that effect the pivot table, +- get additional data based on loaded model. + +.. _sidebar: +.. figure:: media/image144.png + + Side bar. + +The side bar shows the **Menu**. This area let you customize the Olap layout. As highlighted in the figure below, the Menu is divided in three subsections: + +- drill options (a), +- OLAP functions (b), +- table functions (c), +- what if. + +.. _sidebarmenu: +.. figure:: media/image145a.png + + Side bar Menu. + +We start introducing the interface and leave the description to the next *Functionalities* paragraph. In particular, referring to next figure, drill types consists of: + +- position (a), +- member (b), +- replace (c), +- drill through (d). + +.. _drilltypes: +.. figure:: media/image146.png + + Drill types. + +Meanwhile, referring to the following figure, the OLAP functions consist of: + +- show MDX (a), +- reload model (b). + +.. _olapfunctions: +.. figure:: media/image147a.png + + OLAP functions. + +Referring to figure below, table functions consist of: + +- show parent members (a), +- sorting settings (b), +- save customized view (c), +- show properties (d), +- suppress empty rows/columns (e), +- hide spans (f), +- calculated field wizard (g). + +.. _tablefunctions1: +.. figure:: media/image148a.png + + Table functions. + +Referring to next figure, what if consists of: + +- lock/unlock model (a), +- delete versions (b), +- select an algotithm (c), +- output wizard (d), +- save as new version (e), +- undo (f), +- export excel for edit (g). + +.. _tablefunctions2: +.. figure:: media/image149a.png + + Table functions. + +Functionalities +---------------- + +Placing hierarchies on axes +``` + +Como ya dijimos, el usuario puede mover fácilmente una dimensión de la barra de filtro al eje o viceversa arrastrándola y soltándola al lugar deseado. + +Supongamos que queremos mover una cota del panel de filtro al eje de columnas. Los pasos se resumen en la siguiente figura + +.. figura:: media/image150.png + + Move a hierarchy to the columns axis. + +Viceversa, para mover hacia atrás la cota desde el eje de columnas hasta el panel de filtro, el usuario simplemente debe arrastrar y soltar la cota de un lugar a otro como en la siguiente figura. + +.. figura:: media/image151.png + + Move a dimension from the columns axis to the filter panel. + +Del mismo modo, una cota se puede mover desde el panel de filtro al eje de filas simplemente arrastrándola y soltándola de un lugar a otro. + +Intercambio de ejes + +``` + +To swap axes the user should click on the icon |image151|. The user will get the outcome showed in figure below. + +.. |image151| image:: media/image152.png + :width: 30 + +.. figure:: media/image153.png + + Swap axes. + +Selecting different hierarchies on dimension +``` + +Si se define un esquema OLAP, el usuario puede elegir diferentes jerarquías de la misma dimensión. El icono para abrir el cuadro de diálogo se coloca en la esquina superior izquierda de la tarjeta de filtro (si la dimensión tiene más de una jerarquía). Seleccione el icono de jerarquías subrayado a continuación. + +.. figura:: media/image154.png + + Hierarchies icon. + +Se mostrará una ventana emergente. La siguiente figura muestra sus características. La ventana presentará: + +* el nombre de la dimensión (a), +* nombre de las jerarquías seleccionadas (b), +* lista desplegable de jerarquías disponibles (c), +* botón Guardar (d), +* botón cancelar (e). + +.. \_hierarchiesdialogpopup: +.. figura:: media/image155.png + + Hierarchies dialog pop up. + +Después de seleccionar la jerarquía y guardar la elección del usuario, la tabla dinámica utilizará esa jerarquía. + +Si el usuario vuelve a abrir la ventana de diálogo, ve las hieararquías seleccionadas y tiene la oportunidad de cambiarlas si es necesario, como se muestra a continuación. + +.. figura:: media/image1565758.png + + Changing the hierarchies. + +Damos un ejemplo de la salida cuando la jerarquía "Tiempo" se selecciona en la primera figura siguiente y la jerarquía "Tiempo semanal" en la segunda figura siguiente. + +.. \_timehierarchieshowsdays: +.. figura:: media/image159.png + + Time hierachy: the table shows days in the month. + +.. \_timeweeklyhierarchyshowsweek: +.. figura:: media/image160.png + + Time Weekly hierachy: table shows weeks in the month. + +Rebanar + +``` + +The slicing operation consists in the analysis of a subset of a multi-dimensional array corresponding to a single value for one or more members of the dimensions. In order to perform this operation you need to drag and drop the dimesion of interest in the axis panel. Then clicking on the filter icon choose the new single focus and apply it. Once concluded these steps the cube will show only the selected level of the dimension, while the others have been sliced out. + +The following figure shows the slicer option panel which consists of: + +- a dimension name (a), +- a search input field (b), +- a search button (c), +- a show/hide siblings checkbox (d), +- a member tree (e), +- a selected member icon (f), +- a highlighted member (result of searching) (g), +- a save and a cancel buttons (h). + +.. _dialogforslicerchoosing: +.. figure:: media/image161.png + + Dialog for slicer choosing. + +In particular, it is possible to search for a member in three ways: + +1. by browsing the member tree; + +.. figure:: media/image162.png + + Browsing the member tree. + +2. by typing member’s name or it’s part in the input field and clicking on the search button. The research will be possible if the user enters at least four letters. If the user wishes to include member’s siblings to the research, the checkbox (:numref:`dialogforslicerchoosing` (d))needs to be checked; + +.. figure:: media/image16364.png + + Using the research box. + +3. after the first research, if the user types some other member’s name before clicking on the search button, visible members whose names contains a entered text will be highlighted. + +.. figure:: media/image165.png + + Using the research box after a first investigation. + +Once the selection has been saved, the users choice will affect the pivot table and the filter cards slicer name will rearrange. + +Filtering +``` + +Para filtrar los miembros de dimensión en una tabla dinámica, el usuario debe hacer clic en un botón (consulte :numref:`featuresoffiltcard`) situado en el lado derecho de la tarjeta de filtro de dimensiones colocada en el área del filtro. + +El procedimiento para buscar un miembro mediante el cuadro de diálogo de filtro no tiene diferencias significativas con el descrito para el cuadro de diálogo de selección de segmentación de datos. La interfaz emergente es la que se muestra a continuación. Después de seleccionar un miembro, el usuario debe hacer clic en el botón Guardar. La tabla dinámica mostrará los cambios. De lo contrario, haga clic en el botón Cancelar para descartar los cambios. + +.. figura:: media/image166.png + + Filter dialog. + +.. figura:: media/image167.png + + Filter effects on pivot table. + +Profundizar y profundizar + +``` + +User can choose between drill types by clicking on one of the three buttons in the drill types section of the side bar. There are three drill types. In the following we give some details on them. + +1. **Position**: this is the default drill type. Clicking on a drill down/drill up command will expand/collapse a pivot table with child members of a member with that particular command. See below. + +.. figure:: media/image168.png + + “Position” drill down. + +2. **Member**: if the user wants to perform drill operation not only on one member per time but on all members of the same name and level at the same time it is needed to select member drill type. See below. + +.. figure:: media/image169.png + + “Member” drill down. + +3. **Replace**: This option lets the user replace the parent member with his child member during drill down operation. To drill up the user should click on the arrow icon next to the dimension name on which to perform operation. See figure below. + +.. figure:: media/image170.png + + “Replace” drill down. + +Drill through +~~~~~~~~~~~~~ + +To perform drill through operation the user needs first to select a cell, as in the following figure, on which to perform operations. Then clicking on the button for a drill through in the side bar, a dialog will open with results (this pop up could take some time to open). + +.. figure:: media/image171.png + + Drill thorugh option. + +In particular, referring to the next figure, drill though dialog consists of: + +- a hierarchy menu (a), +- a table of values (b), +- a maximum rows drop down list (c), +- a pagination (d), +- a apply button (e), +- a export button (f), +- a cancel button (g), +- a clear all button (h). + +.. _drillthoroughwindow: +.. figure:: media/image172a.png + + Drill thorugh window. + +The user must therefore select a cell, open the side bar and select the drill through item from the panel. A pop up will show up: here the user can choose the level of detail with which data will be displayed. The steps to follow are: + +1. to click on hierarchy in hierarchy menu, + +2. to check the checkbox of the level, + +3. to click on the “Apply” button (after checking the checkbox, remember to click outside of the level list and then select apply). + +The user can also select the maximum rows to load by choosing one of the options in the drop down list (see figure above, (c)). Finally, loaded data can be exported in csv format by clicking on the “Export” button. + +Refreshing model +~~~~~~~~~~~~~~~~ + +To refresh a loaded model the user needs to click on the “Refresh” button available in the side bar panel. This action will clear the cash, load pivot table and the rest of data again. + + +Showing MDX +~~~~~~~~~~~ + +To show current mdx query user should click on show mdx button in the side bar. Figure below shows an example. + +.. figure:: media/image173.png + + Showing MDX query example. + + +Sending MDX +~~~~~~~~~~~ + +If you want to execute an MDX query you need to: + +- click on send MDX button in the sidebar, +- type a query in a text area of send MDX dialogs, +- click on the save button. + +.. figure:: media/image174.png + + Sending MDX query example. + +Result of the MDX query “should” appear in pivot table as in figure below. In fact, the user is responsable for entering *valid* MDX query. + +.. figure:: media/image175.png + + Sending MDX query example. + + +Showing parent members +~~~~~~~~~~~~~~~~~~~~~~ + +If a user wants to see additional information about members shown in the pivot table (for example: member’s hierarchy, level or parent member) he should click on a show parent members button in the side bar panel. The result will be visible in the pivot table. An example is shown in the following two figures. + +.. figure:: media/image176.png + + Pivot table without the parent members mode. + +.. figure:: media/image177.png + + Pivot table after the parent members selection. + +Hiding/showing spans +~~~~~~~~~~~~~~~~~~~~ + +To hide or show spans the user should click on show/hide spans button in the side bar. The result will be visible in pivot table as in figure below. + +.. figure:: media/image178.png + + Hide/show spans. + +Showing properties +~~~~~~~~~~~~~~~~~~ + +In OLAP schema the XML member properties, if configured, could be represented in two possible ways: + +1. as part of pivot table where a property values are placed in rows and columns. To get these values, the user needs to click on show properties button in the side bar. Results will be shown in the pivot table; + +.. figure:: media/image179.png + + Show properties. + +2. in a pop up as compact properties. To enable compact properties user should click on enable compact properties button in the side bar. In this way in all the cells of members Suppressing empty colunms/rows which has property set, a table icon appears. This icon lets the property pop up opens. Figure below shows an example. + +.. figure:: media/image180a.png + + Show properties summarized in a pop up. + +Suppressing empty colunms/rows +``` + +Para ocultar las filas vacías y/o colums, si las hubiera, de la tabla dinámica, el usuario puede hacer clic en el botón "Suprimir filas/colums vacías" en el panel de la barra lateral. Un ejemplo se da en la Figura a continuación. + +.. figura:: media/image181.png + + Suppressing empty colunms/rows. + +Ordenación + +``` + +To enable member ordering the user must click on the “Enable sorting” button in the side bar panel. The command for sorting will appear next to the member’s name in the pivot table. In addition, the sorting command will show the members of “Measures” hieararchy or members that are crossjoined with them, as shown below. + +.. figure:: media/image18283.png + + Member sorting. + +To sort members the user needs to click on the sorting command |image179|, available next to each member of the pivot table. Note that the sorting criteria is ascending at first execution. If the user clicks on the sorting icon, criteria will change to descending and the result will be shown in pivot table. + +.. |image179| image:: media/image184.png + :width: 65 + +To remove the sorting, the user just have to click on the icon again. To change sorting mode user should click on sorting settings button in the side bar. Referring to the following figure, dialog sorting settings consists of: + +.. figure:: media/image185a.png + + Sorting settings window. + +- sorting modes (a), +- no sorting (by default) (b), +- basic (c), +- breaking (d), +- count (e), +- a number input field for count mode definition (f), +- a save button (g). + +Note that “breaking mode” means that the hierarchy will be broken. + +If the user selects “Count sorting” mode the top or last 10 members will be shown by default in the pivot table. Furthermore, the user can also define a custom number of members that should be shown. + +Calculated members and sets +``` + +En primer lugar, hacemos hincapié en que para permitir **Campos calculados** en su documento Olap se necesita una etiqueta de botón adecuada en su plantilla Olap. Tal etiqueta es \. + +Una vez habilitado, para crear un miembro/conjunto calculado, el usuario debe: + +.. figura:: media/image186.png + +Miembro calculado. + +1. seleccionar un miembro de la tabla dinámica, como en la figura anterior, que será el elemento primario del miembro calculado, + +2. haga clic en el botón "campo calculado" en el panel de la barra lateral: aparecerá un cuadro de diálogo "Seleccionar función". Este último consiste en (consulte la siguiente figura): + + * un campo de entrada de nombre (a), + * una ficha de funciones de agregación (b), + * una ficha de funciones aritméticas (c), + * una ficha de funciones temporales (d), + * una ficha de funciones personalizadas (e), + * una ficha de funciones recientes (f), + * una lista de funciones disponibles (g), + * ok y botones de cancelación (h). + +.. \_selectfunctiondialog: +.. figura:: media/image187.png + + Select function dialog. + +La definición de función utilizada para crear miembros calculados se lee desde la carpeta formula.xml archivo, ubicado en: ROOT/resources/yourTennant/Olap. Las funciones están divididas por pocas pestañas diferentes. En particular,\ **Pestaña Reciente** contiene miembros calculados y conjuntos calculados creados por el usuario y guardados en cookies. Si no hay conjuntos /miembros almacenados en las cookies, esa pestaña estará vacía. **Pestaña Personalizada** es donde definir funciones personalizadas. Estas funciones se pueden utilizar para realizar operaciones realmente complejas que no forman parte de funciones MDX predefinidas. Allí puede usar la combinación de pocas funciones juntas o usar operadores para cálculos matemáticos complejos. También se definen en fórmulas xml. Si una pestaña específica no contiene ninguna fórmula, no se mostrará. El campo "Nombre" es obligatorio, de hecho, la creación de una función sin nombre está prohibida. En **Pestaña reciente**, el campo "Nombre" está oculto. la siguiente figura proporciona un ejemplo de fórmula editada en el archivo formulas.xml. + +.. figura:: media/image188.png + + Example of one formula inside of formulas xml. + +3. Seleccione una función e ingrese un nombre de miembro / conjunto calculado y haga clic en "Aceptar". Aparecerá un cuadro de diálogo para la definición de argumentos, como se muestra en la siguiente figura. Este se compone de los siguientes elementos: + +* nombre de función seleccionado (a), +* descripción de la función (b), +* campos de entrada de texto para la expresión del argumento (c), +* tipo de retorno de expresión MDX esperado (d), +* descripción de la expresión MDX del argumento (e), +* abrir botón guardado (f), +* seleccionar del botón de tabla (g), +* ok y botones de cancelación (h). + +.. \_argumentdefdialog: +.. figura:: media/image189.png + + Argument defintion dialog. + +En particular, para introducir el argumento de expresión MDX, el usuario tiene tres opciones, enumeradas a continuación. + +1. Escríbalo manualmente (para usuarios avanzados). + +2. Seleccionar miembros de la tabla dinámica: para seleccionar un miembro que se va a incluir en un conjunto, el usuario debe (ver siguiente figura): + + * haga clic en el botón Seleccionar de la tabla, + * haga clic en los miembros de una tabla dinámica, + * haga clic en Aceptar en el cuadro de diálogo para finalizar la selección. + +.. \_selectingmembers: +.. figura:: media/image190.png + + Selecting members. + +La expresión de los miembros seleccionados se importará en campos de entrada de texto para la expresión del argumento, como se muestra en la figura siguiente. + +.. figura:: media/image191.png + + Expression of the selected members. + +3. Importar expresión de miembros o conjuntos calculados guardados. Para importar un miembro/conjunto calculado, el usuario debe: + + • Haga clic en el botón Abrir guardado. A continuación, aparecerá el cuadro de diálogo de miembros/conjuntos calculados guardados (siguiente figura) y consta de: + + * una lista de los miembros y conjuntos calculados guardados, + * un nombre de miembro/conjunto calculado, + * el tipo de retorno de miembro/conjunto calculado se muestra mediante un icono redondo. + +.. \_savedsetsdialog: +.. figura:: media/image192.png + + Saved sets dialog. + +• Haga clic en miembro/conjunto calculado. La expresión de miembro/conjunto calculado guardado se importará en campos de entrada de texto para la expresión del argumento, como se resalta a continuación. + +.. figura:: media/image193.png + + Expression of the saved/calculated member/set. + +• Después de completar todos los argumentos de función, al hacer clic en el botón Aceptar: + + - add calculated member in a pivot table, + - save calculated set and it will be available for creation of other calculated member and sets. + +En la pestaña "Reciente", abriendo el cuadro de diálogo "Seleccionar función", el usuario puede encontrar una lista de miembros y conjuntos calculados guardados que se pueden editar o eliminar. La edición se realiza haciendo clic en uno de ellos. + +.. figura:: media/image194.png + +Edite un miembro calculado. + +La eliminación se realiza mediante el botón Eliminar como se muestra en la figura anterior. + +## Creación de un documento OLAP\* + +El análisis multidimensional permite la indagación jerárquica de medidas numéricas sobre dimensiones predefinidas. En Cockpit explicamos cómo el usuario puede monitorizar los datos en diferentes niveles de detalle y desde diferentes perspectivas. Aquí queremos entrar en detalles de cómo un usuario técnico puede crear un documento OLAP. Recordamos que las principales características de los documentos OLAP son: + +* la necesidad de una estructura de datos específica (lógica o física); +* análisis basado en dimensiones, jerarquías y medidas; +* análisis interactivo; +* libertad para reorientar el análisis; +* diferentes niveles de análisis de datos, a través de vistas sintéticas y detalladas; +* drill-down, slice and dice, drill-through operations. + +Teniendo en cuenta estos elementos, describiremos los pasos para desarrollar un documento OLAP. + +Acerca del motor + +``` + +Knowage performs OLAP documents by relying on the **OLAP engine**. This engine integrates Mondrian OLAP server and two different cube navigation clients to provide multi-dimensional analysis. In general, Mondrian is a Relational Online Analytical Processing (ROLAP) tool that provides the back-end support for the engine. OLAP structures, such as cubes, dimensions and attributes, are mapped directly onto tables and columns of the data warehouse. This way, Mondrian builds an OLAP cube in cache that can be accessed by client applications. The Knowage OLAP engine provides the front-end tool to interact with Mondrian servers and shows the results via the typical OLAP functionalities, like drill down, slicing and dicing on a multi-dimensional table. Furthermore, it can also interact with XMLA servers. This frontend translates user’s navigation actions into MDX queries on the multi-dimensional cube, and show query results on the table he is navigating. + + +Development of an OLAP document +``` + +La creación de un documento analítico OLAP requiere los siguientes pasos: + +* modelado de esquemas; +* configuración del catálogo; +* Construcción de plantillas de cubos OLAP; +* creación de documentos analíticos. + +Modelado de esquemas +^^^^^^^^^^^^^^^^^ + +El primer paso para un análisis multidimensional es identificar la información esencial que describe el proceso / evento bajo análisis y considerar cómo se almacena y organiza en la base de datos. Sobre la base de estos dos elementos, se debe realizar un proceso de mapeo para crear el modelo multidimensional. + +.. indirecta:: + + **From the relational to the multi-dimensional model** + + The logical structure of the database has an impact on the mapping approach to be adopted when creating the multidimensional model, as well as on query performances. + +Si la estructura del esquema relacional cumple con lógicas multidimensionales, será más fácil asignar las entidades del modelo físico a los metadatos utilizados en los esquemas de Mondrian. De lo contrario, si la estructura es altamente normalizada y escasamente dimensional, el proceso de mapeo probablemente requerirá forzar y aproximar el modelo para obtener un modelo multidimensional. Como se dijo anteriormente, Mondrian es una herramienta ROLAP. Como tal, mapea estructuras OLAP, como cubos, dimensiones y atributos directamente en tablas y columnas de una base de datos relacional a través de archivos basados en XML, llamados esquemas Mondrian. Los esquemas de Mondrian son tratados por Knowage como recursos y organizados en catálogos. A continuación, un ejemplo de esquema de Mondrian en ejemplo de esquema de Mondrian: + +.. code-block:: xml +:linenos: +:caption: Ejemplo de esquema de Mondrian + + + + + + + + + + + + + ... + + ... + + + + +
+ + ... + + + + + + +
+ + + + ... + + + + + + + + + ... + + + + + + [Measures].[Store Sales] - [Measures].[Store Cost] + + + + + + + ... + + +Cada archivo de asignación contiene un solo esquema, así como varias dimensiones y cubos. Los cubos incluyen múltiples dimensiones y medidas. Las dimensiones incluyen múltiples jerarquías y niveles. Las medidas pueden ser primitivas, es decir, enlazadas a columnas individuales de la tabla de hechos, o calculadas, es decir, derivadas de fórmulas de cálculo que se definen en el esquema. El esquema también contiene vínculos entre los elementos del modelo OLAP y las entidades del modelo físico: por ejemplo,
establece un vínculo entre un cubo y sus dimensiones, mientras que los atributos primaryKey y foreignKey hacen referencia a las restricciones de integridad del esquema en estrella. + +.. nota:: +**Mondrian** + +``` + For a detailed explanation of Mondrian schemas, please refer to the documentation available at the official project webpage: http://mondrian.pentaho.com/. + + +``` + +Configuración del catálogo de motores +\+++++++++++++++++++++++++++++++ + +Para hacer referencia a un cubo OLAP, primero inserte el esquema Mondrian correspondiente en el catálogo de esquemas administrados por el motor. Para hacer esto, vaya a **Catálogos> catálogo de esquemas de Mondrian**. Aquí puede definir el nuevo esquema cargando su archivo de esquema XML y eligiendo **Nombre** y **Descripción**. Al crear una nueva plantilla OLAP, elegirá entre los cubos disponibles definidos en los esquemas registrados. + +Tenga en cuenta que la opción Bloquear prohíbe a otros usuarios técnicos modificar la configuración. + +Creación de plantillas OLAP +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Una vez que se ha creado el cubo, debe crear una plantilla que asigne el cubo al documento analítico. Para lograr este objetivo, el usuario debe editar manualmente la plantilla. La plantilla es un archivo XML que le dice al motor OLAP de Knowage cómo navegar por el cubo OLAP y tiene una estructura como la representada en el siguiente código: + +.. \_mappingtemplateexample: +.. code-block:: xml +:linenos: +:caption: Ejemplo de plantilla de asignación + + + + + + + + + SELECT {[Measures].[Unit Sales]} ON COLUMNS + , {[Region].[All Regions]} ON ROWS + FROM [Sales] + WHERE [Product].[All Products].[${family}] + + + + + SELECT {[Measures].[Unit Sales]} ON COLUMNS + , {[Region].[All Regions]} ON ROWS + FROM [Sales] + WHERE [Product].[All Products].[Drink] + + + + + + + + + + + + + + + + + +A continuación se explican las diferentes secciones del ejemplo de plantilla de asignación. + +* La sección CUBE establece el esquema de Mondrian. Debe hacer referencia al nombre exacto del esquema, tal como se registra en el catálogo en el servidor. +* La sección MDXMondrianQuery contiene la consulta MDX original que define la vista inicial (columnas y filas) del documento OLAP. +* La sección MDX contiene una variación de la consulta MDX original, tal como la utiliza el motor de Knowage. Esta versión incluye parámetros (si los hay). El nombre del parámetro permitirá a Knowage vincular el controlador analítico asociado al documento a través del parámetro (en el servidor). +* La sección TOOLBAR se utiliza para configurar las opciones de visibilidad de la barra de herramientas en el documento OLAP. El significado exacto y las funcionalidades de cada botón de la barra de herramientas se explican en las siguientes secciones. Una lista más completa de las opciones disponibles se muestra en Opciones configurables del menú: + +.. code-block:: xml +:linenos: +:caption: Opciones configurables del menú + + + + + + + + + + + + + + + + + + +Creación del documento analítico +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Una vez que tenga la plantilla lista, puede crear el documento OLAP en Knowage Server. + +Para crear un nuevo documento OLAP, haga clic en el botón "crear un nuevo documento" en el **Desarrollo de documentos** y seleccione **Procesamiento analítico en línea** como Tipo. Luego puede elegir los motores disponibles. En este caso solo tenemos el **Motor OLAP**. + +Escriba un nombre, una funcionalidad, cargue la plantilla XML y guárdela. Verá el documento en la funcionalidad (carpeta) que seleccionó, que se muestra con el típico icono de cubo como se muestra a continuación. + +.. \_olapdocserver: +.. figura:: media/image195.png + + OLAP document on server. + +Diseñador OLAP\* + +``` + +Knowage Server is also endowed of an efficient OLAP designer which avoid the user to edit manually the XML-based template that we discussed on in Development of an OLAP document. We will therefore describe here all features of this functionality. + +The user needs to have a functioning Modrian schema to start the work with. Select **Mondrian Schemas Catalog** to check the available Mondrian schemas on server. It is mandatory that the chosen Mondrian schema has no parameters applied. + +.. warning:: + **Mondrian schema for OLAP designer** + + The Mondrian schema must not be filtered thorough any parameter or profile attribute. + +The page as the one in figure below will open. + +.. figure:: media/image196.png + + Schema Mondrian from catalog. + +Then we start entering the **Document Browser** and clicking on the “Plus” icon at the top right corner of the page. Fill in the mandatory boxes as Label and Name of the document, select the On-line Analytica Process Type of document and the What-if Engine (we stress that the What-if engine is available only for who have purchased the Knowage SI package). Remember to save to move to the next step: open the Template Build. The latter can be opend clicking on the editor icon |image195| and it is available at the bottom of the document detail page. + +.. |image195| image:: media/image197.png + :width: 30 + +The action opens a first page asking for the kind of template. Here we choose the Mondrian one. Consequently you will be asked to choose the Mondrian Schema and after that to select a cube. Next figure sums up these three steps. Following the example just given below you will enter a page like that of the second figure below. + +.. _olapcoreconfig: +.. figure:: media/image198.png + + OLAP core configuration. + +.. _definingolaptempl: +.. figure:: media/image199.png + + Defining OLAP template. + +Once entered the page the user can freely set the fields as filter panels or as filter cards, according to requirements. Refer to *Functionalities* Chapter to review the terminology. Make your selection and you can already save the template as shown below. + +.. _definingolaptempl2: +.. figure:: media/image200.png + + Defining OLAP template. + +You can notice that the side panel contains some features (see next figure): + +.. _sidepanelfeatolapdes: +.. figure:: media/image201.png + + Side panel features for the OLAP Designer. + +- |image200| to set the drill on Position, Member or Replace; + +.. |image200| image:: media/image202.png + :width: 30 + +- |image201| to configure the scenario; + +.. |image201| image:: media/image203.png + :width: 30 + +- |image202| to define the cross navigation; + +.. |image202| image:: media/image204.png + :width: 30 + +- |image203| to configure buttons visibility. + +.. |image203| image:: media/image205.png + :width: 30 + +Refer to Section *Functionalities* to recall the action of the different drills. To select between them will affect the navigation of the OLAP outputs by users. Instead the scenario is used to allow the end-user to edit or not the records contained in the OLAP table. The user is first asked to select the cube in order to get the measures that the admin lets the end-user the permission to edit and modify. Referring to to the following figure, an admin user must simply check the measures using the wizard. At the bottom of the page there is also the possibility to add a parameter that can be used by the end-user when editing the measure, for example if one has a frequent multiplication factor that changes accordingly to the user’s needs, the end-user can use that factor to edit measures and ask the admin to update it periodically. + +.. _wizconfigscena: +.. figure:: media/image20607.png + + Wizard to configure the scenario. + +Once one cross navigation has been set you keep on adding as many as required. Just open the wizard and click on the “Add” button at the top right corner. + +Note that the parameter name will be used to configure the (external) cross navigation. In fact, to properly set the cross navigation the the user must access the “Cross Navigation Definition” functionalities available in Knowage Server. Here, referring to *Cross Navigation* section of *Analytical document* chapter, you will use the parameter just set as output parameter. + +.. figure:: media/image2080910.png + + Cross navigation definition. + +As shown in figure below, the buttons visibility serves to decide which permissions are granted to the end-user. Some features can only be let visible while the admin can also grant the selection for others. + +.. figure:: media/image211.png + + Wizard to configure the scenario. + +Once the configuration is done click on the **Save template** button and on the **Close designer** button to exit template. As :numref:`sidepanelfeatolapdes` highlights, these two buttons are available at the bottom of the side panel. + +The admin can develop the OLAP document using also the OLAP engine. In this case the OLAP designer will lack of the scenario configuration since in this case the end-user must not have the grants for editing the records. So in this instance the “Configure scenario” button is not available at all. For the other two options the instructions are right the same as the What-if engine. + + +Profiled access +^^^^^^^^^^^^^^^^^^^^^^ + +As for any other analytical document, Knowage provides filtered access to data via its behavioural model. The behavioural model is a very important concept in Knowage. For a full understanding of its meaning and functionalities, please refer to Behavioural Model. + +Knowage offers the possibility to regulate data visibility based on user profiles. Data visibility can be profiled at the level of the OLAP cube, namely the cube itself is filtered and all queries over that cube share the same data visibility criteria. + +To set the filter, which is based on the attribute (or attributes) in the user’s profile, the tecnical user has to type the Mondrian schema. We report Cube level profilation example as a reference guide. Note that data profiling is performed on the cube directly since the filter acts on the data retrieval logics of the Mondrian Server. So the user can only see the data that have been got back by the server according to the filter. + + +.. code-block:: xml + :linenos: + :caption: Cube level profilation example. + + + + .... +
+ ... + + + + + + SELECT pc.product_family as product_family, p.product_id as + product_id, + p.product_name as product_name, + p.brand_name as brand_name, pc.product_subcategory as + product_subcategory, pc.product_category as product_category, + pc.product_department as product_department + FROM product as p + JOIN product_class as pc ON p.product_class_id = pc. + product_class_id + WHERE and pc.product_family = '${family}' + + + + + + + + + + + + + ... + + +In the above example, the filter is implemented within the SQL query that defines the dimension using the usual syntax “pr.product_family = '${family}'”. + +The value of the “family” user profile attribute will replace the ${family} placeholder in the dimension definition. + +You can filter more than one dimensions/cubes and use more profile attributes. The engine substitutes into the query the exact value of the attribute; in case of a multi value attribute to insert in an SQL-IN clause you will have to give the attribute a value like ’value1’, ’value2’, and insert into the query a condition like “and pc.product_family IN (${family})”. + +Once the OLAP document has been created using the template designer the user can insert parameters to profile the document. To set parameters the user has to download the Mondrian schema and edit it; modify the dimension(s) (that will update according to the value parameter(s)) inserting an SQL query which presents the parametric filtering clause. + +.. hint:: + **Filter through the interface** + + Note that for the OLAP instance, it has not proper sense to talk about “general” parameters. In this case we only deal with profile attributes while all the filtering issue is performed through the interface, using the filter panel. + +Cross Navigation +``` + +La navegación cruzada debe implementarse a nivel de plantilla, pero también a nivel de documento analítico. Este último ya ha sido descrito salvajemente en Cross Navigation. A continuación veremos el primer caso. Observe que ambos procedimientos son obligatorios. + +Para los documentos OLAP es posible habilitar la navegación cruzada en miembros o en celdas y daremos más detalles sobre estos dos casos a continuación. + +En términos generales, el usuario debe modificar el archivo de plantilla para configurar la navegación cruzada con el fin de eliminar los parámetros de salida del documento. Recordamos que la definición de los parámetros de salida se discute en *Navegación cruzada* sección de *Documento analítico* capítulo de este manual. + +Navegación cruzada en miembros +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Activar la navegación cruzada en un miembro significa que el usuario puede hacer clic en un miembro de una dimensión que se va a enviar y visualizar un documento de destino. El primer tipo de navegación se puede establecer editando la plantilla de consulta OLAP. En el primer caso, debe agregar una sección llamada "clicable" dentro de la etiqueta de consulta MDX. En realidad + +* el valor del atributo es igual al nivel jerárquico que contiene los miembros en los que se podrá hacer clic; +* el elemento representa el parámetro que se pasará al documento de destino. El atributo name es el URI del parámetro que se pasará al documento de destino. El valor 0 representa el miembro seleccionado actualmente, como una convención: este valor se asignará al parámetro cuyo URI es null. + +La siguiente figura da un ejemplo. Tenga en cuenta que puede reconocer que la navegación cruzada se activa cuando los elementos se muestran resaltados y subrayados en azul. + +.. figura:: media/image212.png + + Cross navigation on member. + +Si abre el archivo de plantilla, leerá instrucciones similares a las que se informan en Sintaxis utilizada para establecer la navegación cruzada. + +.. code-block:: xml +:linenos: +:caption: Sintaxis utilizada para establecer la navegación cruzada. + + + select {[Measures].[Unit Sales]} ON COLUMNS, + {([Region].[All Regions], [Product].[All Products])} ON ROWS from + [Sales_V] + + + + + +Navegación cruzada desde una celda de la tabla dinámica +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Este caso es similar al taladro de una dimensión, excepto que en este caso los valores de todas las dimensiones se pueden pasar al documento de destino. En otras palabras, se puede pasar todo el contexto dimensional de una célula. Ahora supongamos que el usuario desea hacer clic en una celda y pasar al documento de destino el valor de la familia de niveles de dimensión del producto y dimensión del año de tiempo. Debe crear dos parámetros, uno para la familia donde la dimensión es el producto, la jerarquía es el producto, el nivel es la familia del producto y otro para el parámetro del año donde la dimensión en el tipo, la jerarquía es el tiempo y el nivel es el año. Veamos lo que sucede cuando el usuario hace clic en una celda. Dependiendo de la celda seleccionada, la familia de controladores analíticos del documento de destino tendrá un valor diferente: será el nombre del miembro de contexto (de la celda seleccionada) de la dimensión "Producto", es decir, la jerarquía \[Producto], en \[Producto]. Nivel \[ProductFamily]. Consulte la siguiente tabla para ver algunos ejemplos: + +.. tabla:: Miembro de contexto en la dimensión del producto +:widths: automático + + +-----------------------------------------------------------------+-----------------------------------------------------+ + | Context member on Product dimension | "Family" analytical driver value | + +=================================================================+=====================================================+ + | [Product].[All Products] | [no value: it will be prompted to the user] | + +-----------------------------------------------------------------+-----------------------------------------------------+ + | [Product].[All Products].[Food] | Food | + +-----------------------------------------------------------------+-----------------------------------------------------+ + | [Product].[All Products].[Drink] | Drink | + +-----------------------------------------------------------------+-----------------------------------------------------+ + | [Product].[All Products].[Non-Consumable] | Non-Consumable | + +-----------------------------------------------------------------+-----------------------------------------------------+ + | [Product].[All Products].[Food].[Snacks] | Food | + +-----------------------------------------------------------------+-----------------------------------------------------+ + | [Product].[All Products].[Food].[Snacks].[Candy] | Food | + +-----------------------------------------------------------------+-----------------------------------------------------+ + +Echemos un vistazo a la plantilla. La sintaxis utilizada para establecer la navegación cruzada muestra cómo usar la etiqueta de navegación cruzada: + +.. code-block:: xml +:linenos: +:caption: Sintaxis utilizada para establecer la navegación cruzada. + + + + + + + + +Una flecha verde será visible en la barra de herramientas para mostrar que la navegación cruzada está habilitada. Cuando el usuario hace clic en ese icono en cada celda, se mostrará una flecha verde en cada celda. El usuario puede hacer clic en ese icono para iniciar la navegación cruzada desde una celda. diff --git a/functionalities-guide/news-management/index.es.rst b/functionalities-guide/news-management/index.es.rst new file mode 100644 index 00000000..2a702cc0 --- /dev/null +++ b/functionalities-guide/news-management/index.es.rst @@ -0,0 +1,50 @@ +# Gestión de noticias + +El **gestión de noticias** es una funcionalidad útil para mantener al usuario final constantemente informado sobre cualquier cambio o actualización en la propia plataforma Knowage. En esta sección describiremos los pasos principales para insertar una noticia de última hora. + +## Cómo publicar noticias + +Para poner las noticias en su lugar es obligatorio tener privilegios de la administración. Un usuario administrador puede insertar las noticias ingresando a la funcionalidad de "administración de noticias" desde el menú principal de Knowage, como se destaca en la siguiente imagen: + +.. figura:: media/image01.png + + News management menu item. + +En consecuencia, el usuario es redirigido a la lista de gestión de noticias. La página se divide en dos áreas. En el lado izquierdo, se enumeran todas las noticias insertadas anteriormente. Al hacer clic en uno de ellos, sus detalles se muestran en el lado derecho. + +.. figura:: media/image02.png + + Access news management list. + +Para editar las últimas noticias en su lugar, el usuario debe hacer clic en el botón rojo más icono disponible en el centro de la página. Al hacer clic en el icono, knowage server abre la interfaz que se muestra en la siguiente imagen: + +.. figura:: media/image03.png + + Access news management list. + +Aquí se le pide al usuario que: + +* insertar el título de la noticia, +* insertar la descripción de la noticia, +* insertar el texto de la noticia, +* especificar la fecha de caducidad, es decir, la fecha hasta que las noticias puedan ser visibles desde el usuario final, +* para comprobar/descomprimir una bandera para habilitar/deshabilitar la noticia, +* la lista de los roles que tienen el permiso para leer las noticias. + +Una vez rellenado el formulario de "detalles de noticias" en todas sus partes obligatorias, el usuario puede guardar la noticia utilizando el botón "guardar", disponible en la esquina superior derecha de la página. + +## Cómo el usuario final puede leer las noticias + +Cuando se agregan algunas noticias, el **icono de noticias** informa de la presencia de noticias recientes gracias a un símbolo de mancha roja que resalta también el número de últimas noticias no leídas. + +.. figura:: media/image04.png + + News notification. + +El icono de noticias siempre está disponible en el panel de menú knowage, mientras que el icono rojo permanece inmóvil, el usuario tiene algunas noticias no leídas. Al hacer clic en el icono, aparece la lista de noticias recientes no leídas. + +.. figura:: media/image05.png + + News notification pop up. + +El usuario puede acceder a la información de noticias, simplemente seleccionando la propia noticia de la lista. Finalmente el usuario puede marcarlo como leído. diff --git a/functionalities-guide/registry/index.es.rst b/functionalities-guide/registry/index.es.rst new file mode 100644 index 00000000..8bc260fb --- /dev/null +++ b/functionalities-guide/registry/index.es.rst @@ -0,0 +1,297 @@ +# Registro + +Un documento del Registro permite a los usuarios escribir, cancelar y modificar elementos de un datamart. Knowage permite a los usuarios implementar un documento del Registro a través del **Motor Qbe**. Por cierto, tiene una interfaz gráfica diferente en comparación con la de Qbe. En la siguiente figura se da un ejemplo. En los próximos capítulos veremos cómo navegar por un documento del Registro (*Características del Registro* párrafo) y cómo crear uno nuevo (*Desarrollo de registros* párrafo). + +.. figura:: media/image339.png + + Example of Registry document. + +## Características del Registro + +La ejecución de un documento del Registro abre una tabla simple: los registros se muestran en filas y se pueden navegar utilizando la paginación disponible en la parte inferior de la ventana. Subrayamos que es posible editar cada elemento de la tabla si dentro de la plantilla esa columna está configurada para ser editable. Simplemente haga clic en una celda que desee reorganizar y escriba una cadena o un valor numérico en consecuencia. A continuación se destacan algunos ejemplos. + +.. figura:: media/image340.png + + Editing table cells. + +Además, puede agregar nuevas filas desde cero seleccionando el botón "Agregar fila" |image335| en el encabezado de la última columna. Inserte en cada celda el valor correspondiente: cadena, número o fecha. El botón "Agregar fila" estará disponible si dentro de la plantilla hay una configuración: + +.. |image335| imagen:: media/image341.png +:ancho: 30 + +.. figura:: media/image343.png + + Adding a new row. + +Viceversa, puede eliminar una o más filas usando el icono "Papelera" |image338| en la última columna. El botón "Papelera" estará disponible si dentro de la plantilla hay una configuración: + +.. |image338| imagen:: media/image344.png +:ancho: 30 + +Es importante hacer clic en el botón "Guardar" |image339| para almacenar los ajustes realizados en el datamart. El botón "Guardar" está disponible en la barra de funcionalidad, encima de la tabla. + +.. |image339| imagen:: media/image345.png +:ancho: 30 + +.. \_functionalitybar: +.. figura:: media/image342.png + + Functionality bar. + +Además, puede utilizar filtros, si se implementan, disponibles en la barra de funcionalidad. Haga clic en el icono "Filtro" |image340| para ejecutar la funcionalidad. De lo contrario, haga clic en el icono "Cancelar" para desactivar las casillas. + +.. |image340| imagen:: media/image346.png +:ancho: 30 + +Tenga en cuenta que, dado que los registros se muestran en una tabla simple, está disponible un cuadro combinado (consulte la figura a continuación) que permite al usuario visualizar todos los campos relacionados con el registro de la celda anterior y luego cambiar de uno a otro para obtener todos los datos. + +.. figura:: media/image348.png + + Select one field from a combobox. + +Características de JPivot Registry + +``` + +It is possible to implement also a JPivot Registry document. The graphical features are very similar to the ones exposed in *Registry development* paragraph. An example is given below. + +.. _examplejpivotregdoc: +.. figure:: media/image349.png + + Example of Jpivot Registry document. + +In this case the table shows columns organized in a hierarchical way and a grouping function is implemented. From the left to the right the columns contain fields at different detail levels. The last column in our example in the figure above contains numeric data. Such a field is grouped at the “country” level. The grouping level depends on the configurations made on template building. + +In the JPivot instance it is not allowed to add, modify or cancel rows. Furthermore, it is not permitted to edit cells which contain string items while the numeric ones are still changeable. If implemented, filters are still available. + + +Registry development +-------------------- + +To create a Registry document there must be available a datamart schema on Knowage Server. Then you must edit an XML template. The latter is very similar to the one produced under the Qbe development but in this case you must add an appropriate tag. Indeed, if the template file has the **** tag the engine shows data in registry modality; namely it shows a table whose rows are manageable by end users by adding, editing or deleting them. + +Here we exhibit a possible syntax for a Registry document. + +.. _exampletemplatebuild: +.. code-block:: xml + :linenos: + :caption: Example (a) of template for Registry. + + + + + + + + + + + + + + + + + + + + + + + + + + + +In particular, we give some details for each tag and main attributes. + +- **ENTITY**: the entity name as in the model. It must be the fully-qualified name of the class representing your registry in the model; +- **FILTERS**: possibility to define filters by specifying the title, the field (among shown columns) and the type among COMBO, MANUAL or DRIVER: in this last case user has also to specify the analytical driver that take this filter’s value; +- **COLUMNS**: columns list specifying: + + - **field name**: the reference to the field identifier into the model; + - **title**: the title of the column shown (optional); + - **visible**: the visibility of the column (optional, default true); + - **editable**: the editability of the column (optional, default true); + - **color and format for numbers**: optional; + - **size**: the width of the column (optional); + - **editor**: the editor. Default type is free-text for simple column (not FK values), but for date is possible to show the picker through the type PICKER. The format option specifies the format date; + - **subEntity**: if the column is a reference key, the user can specify the subentity referred and the foreign key name. This value must be equals to the name of the relationship object created in the model. The field shown will be of the entity referred and will be shown as COMBO if editable; + - **foreignKey**: if the subEntity property is set, foreignKey property must be set with the name of the foreign key (to lower case); + - **dependsFrom**: if the column content is logically correlated to other registry’s column, it is possible to specify this logic through this parameter. DependsFrom identifies the field name on which it depends (Optional); + - **dependsFromEntity**: usable only with dependsFrom parameter. It defines a different entity to resolve the correlation (optional); + - **orderBy**: is used in case of foreign key. The combo box is ordered by the column here indicated, by default is the column extracted (optional); + - **infoColumn**: if true ignore the column when inserting or updating the record (optional); + - **defaultValue**: defines the default value for the field; if the user does not set any value for this field during insertion, this value will be set automatically (optional, not allowed if subEntity or foreignKey property is set). For date fields, the correct pattern is "yyyy-MM-dd'T'HH:mm:ss.xxx'Z'". + +We stress that it is mandatory to point at one datamart table using a column with a numeric key. The code line is highlighted in figure below. While, if not elsewhere specified, a descriptive column will be displayed by default. + +.. code-block:: xml + :linenos: + :caption: Pointing at a numerical column. + + + + ... + + + +Still referring to the code above, we underline that the “product_subcategory” field is used as a subcategory. It belongs in fact to another table. In this case it is enough to add the attributes: subEntity="rel_product_class_id_in_product_class" foreignKey="rel_product_class_id_in_product_class". + +Filters +``` + +.. code-block:: xml +:linenos: +:caption: Ejemplo de definición de filtro. + + + + + + + +La definición del filtro permite establecer diferentes propiedades: + +* **título**: el título del filtro; +* **campo**: la referencia al identificador de campo en el modelo; +* **presentación**: COMBO/DRIVER/MANUAL (opcional si static="true"); +* **visible**: la visibilidad del filtro (opcional, por defecto falso); +* **estático**: verdadero/falso. Establezca esta propiedad si desea limitar el valor del filtro a un valor específico (opcional); +* **filterValor**: el valor específico que desea establecer para el filtro (obligatorio si static="true"). Para los campos de fecha, el patrón correcto es "%d/%m/%Y %h:%i:%s". + +Controlador analítico + + Registry filtering by analytical driver is possible using DRIVER value for presentation property in filter TAG. Registry template must contains FILTERS tag. Below an example of configuration for a driver named "UNIT_SALES_AD" insisting on the column "UNIT_SALES". + + .. code-block:: xml + :linenos: + :caption: Pointing at a numerical column. + + + + + + + Profile attributes + +Otra forma de filtrar el contenido del Registro es mediante atributos de perfil. Si desea utilizar atributos de perfil para filtrar valores, debe seguir estos pasos: + +* Crear un atributo de perfil (si es necesario) desde el menú Administrar atributos de perfil +* Asociar el atributo de perfil a la columna durante la creación del modelo + +De esta manera, sus datos serán filtrados por este atributo (si no están vacíos) tanto al ver datos como al insertar o actualizar registros. + +Multivalor + +*** + +Si su atributo de perfil es multivalor, debe: + +* poner *EN* cláusula como *"Tipo de filtro de atributo de perfil"* durante la creación del modelo +* Establecer valores de atributo de perfil que respeten este formato *'value1','value2',...,'valueN'* o *{,{value1,value2,...,valueN}}*. + +De esta manera, el valor del atributo de perfil se tratará como una lista de valores y se aplicará un filtro con este criterio. + +Instancia de JPivot Registry + +``` + +The Registry instance allows to develop also a Jpivot table. See the last figure (above) to have an idea while the syntax example is given in the next code: + +.. code-block:: xml + :linenos: + :caption: Example (b) of template code for Registry. + + + + + + + + + + + + + + + + + + + + + + + + +Note that to activate the JPivot modality it is important to add the attribute type="merge" and have at least one numeric field. Furthermore the selected column fields must be hierarchically structured. + +Logging & auditing +------------------- + +The Registry engine is logging changes performed by users when interacting with Registry documents (insertions/updates/deletions of entries). + +By default, the engine is logging messages such as + +.. code-block:: bash + :linenos: + + 01 feb 2021 11:40:49,750: User is performing operation on entity from model for record: old one is ..., new one is ..., number of changes is ... + +into the ``TOMCAT_HOME/logs/knowageQbeEngineAudit.log`` file. + +In case you want those information to be stored into a database table (for analytical and visualization purposes), you have to create it and then to configure the engine logging system accordingly, following the below example based on MySQL. + +Let's create a table: + +.. code-block:: sql + :linenos: + + CREATE TABLE `LOG_REGISTRY` ( + `AUDIT_ID` INT NOT NULL AUTO_INCREMENT, + `AUDIT_DATETIME` DATETIME NULL, + `AUDIT_OPERATION` VARCHAR(45) NULL, + `AUDIT_USER` VARCHAR(100) NULL, + `AUDIT_CHANGES_NO` INT NULL, + `ENTITY_NAME` VARCHAR(100) NULL, + `MODEL_NAME` VARCHAR(100) NULL, + `ATTRIBUTES_OLD` TEXT NULL, + `ATTRIBUTES_NEW` TEXT NULL, + PRIMARY KEY (`AUDIT_ID`)); + +then edit ``TOMCAT_HOME/webapps/knowageqbeengine/WEB-INF/classes/log4j.properties`` and add: + +.. code-block:: jproperties + :linenos: + + # Define the SQL appender + log4j.appender.sql=it.eng.spagobi.utilities.logging.Log4jJNDIAppender + # JNDI connection to be used + log4j.appender.sql.jndi=java:comp/env/jdbc/knowage + # Set the SQL statement to be executed. + log4j.appender.sql.sql=INSERT INTO LOG_REGISTRY (AUDIT_DATETIME,AUDIT_OPERATION,AUDIT_USER,AUDIT_CHANGES_NO,ENTITY_NAME,MODEL_NAME,ATTRIBUTES_OLD,ATTRIBUTES_NEW) VALUES (now(),'%X{operation}','%X{userId}',%X{variations},'%X{entityName}','%X{modelName}','%X{oldRecord}','%X{newRecord}') + # Define the xml layout for file appender + log4j.appender.sql.layout=org.apache.log4j.PatternLayout + + log4j.logger.it.eng.qbe.datasource.jpa.audit.JPAPersistenceManagerAuditLogger=INFO, FILE_AUDIT + log4j.additivity.it.eng.qbe.datasource.jpa.audit.JPAPersistenceManagerAuditLogger=false + +pay attention to the JNDI name (in case you created the table within Knowage metadata database, then ``java:comp/env/jdbc/knowage`` is fine) then restart Knowage server: this way, when user is interacting with a registry document, the ``LOG_REGISTRY`` (as per the SQL script above) table will contain: + +- ``AUDIT_DATETIME``: the date and time when the operation was performed +- ``AUDIT_OPERATION``: one of the following values: INSERTION/UPDATE/DELETION +- ``AUDIT_USER``: the user who performed the operation +- ``AUDIT_CHANGES_NO``: number of attributes that were actually changed in case of an UPDATE, null otherwise +- ``ENTITY_NAME``: name of the modified entity type +- ``MODEL_NAME``: name of the business model +- ``ATTRIBUTES_OLD``: previous attributes state in case of an UPDATE or DELETION +- ``ATTRIBUTES_NEW``: new attributes state in case of an INSERTION or UPDATE +``` diff --git a/functionalities-guide/resource-manager/index.es.rst b/functionalities-guide/resource-manager/index.es.rst new file mode 100644 index 00000000..01bb8699 --- /dev/null +++ b/functionalities-guide/resource-manager/index.es.rst @@ -0,0 +1,135 @@ +# Administrador de recursos + +.. importante:: +**Solo Enterprise Edition** + + With the Knowage Community Edition the Resource Manager will be able to manage just the **models** folder in order to define metadata for data mining analysis. With the Knowage Enterprise Edition, will be able to manage all Knowage's installation resources. + +El **Administrador de recursos** funcionalidad disponible en el marco del **Herramienta** del menú principal de Knowage, como se muestra en la figura siguiente, le permite administrar todos los archivos dentro de la carpeta Recursos de la instalación de Knowage. En las siguientes secciones veremos en detalle cómo usar la función Administrador de recursos. + +.. figura:: medios/resource_mng\_1.png + + Resource Manager from contextual menu. + +De forma predeterminada, el sistema muestra los archivos que comienzan por el directorio raíz: + +.. figura:: medios/resource_mng\_2.png + + Resource Manager starting view. + +## Funcionalidades de Resource Manager + +La ventana Administrador de recursos reproduce dos secciones: a la izquierda, el árbol que representa los recursos del sistema existentes; a la derecha los detalles de la carpeta izquierda seleccionada. En la parte superior derecha está disponible la ruta actual: + +.. figura:: medios/resource_mng\_2\_bis.png + + Resource Manager detail view. + +**Funcionalidades de árbol** + +El árbol muestra exactamente la estructura física del sistema de archivos desde el **Recursos** carpeta. En la barra superior están presentes dos funcionalidades: **Actualizar árbol** y **Crear nueva carpeta**: + +.. figura:: medios/resource_mng\_0.png + + Tree view. + +.. figura:: medios/resource_mng\_0\_bis.png + + Creation detail. + +.. figura:: medios/resource_mng\_0\_ter.png + + Creation result. + +Preste atención a que la nueva carpeta se crea adjunta a la carpeta seleccionada en el árbol ('KNOWAGE-5058' en este caso). + +Haciendo clic en el icono "Descargar" en una carpeta específica, puede descargar todos los archivos contenidos: + +.. figura:: medios/resource_mng_tree\_1.png + + Download functionality icon. + +Asigne un nombre, seleccione una carpeta para la descarga y el archivo zip estará disponible en su sistema local. + +.. figura:: medios/resource_mng\_3.png + + Download functionality. + +Al hacer clic en el icono "Eliminar" en una carpeta específica, puede eliminar la carpeta físicamente del servidor de Knowage (después de confirmar la operación). Por favor, preste atención porque esta es una operación irreversible. + +.. figura:: medios/resource_mng_tree\_2.png + + Delete functionality icon. + +.. figura:: medios/resource_mng_tree\_3.png + + Delete functionality confirmation. + +**Panel de detalles** + +Cuando se selecciona una carpeta, el panel derecho muestra todos los archivos que contiene. Para cada uno muestra Nombre, Tamaño y Fecha de la última modificación: + +.. figura:: medios/resource_mng\_6.png + + Detail view. + +Todos los elementos son verificables, esto le permite seleccionar cuáles desea descargar o eliminar a través de iconos específicos en la barra de herramientas: + +.. figura:: medios/resource_mng\_7.png + +Funcionalidades masivas disponibles para archivos seleccionados + +Si lo desea, también puede agregar uno o más archivos directamente a través del **Subir** en la parte superior de la lista: + +.. figura:: medios/resource_mng\_5.png + +Subir archivos + +.. figura:: medios/resource_mng\_5\_bis.png + +Ventana emergente de archivo de selección + +En este contexto, si carga un archivo zip, puede elegir si desea administrar el archivo comprimido: + +.. figura:: medios/resource_mng\_5\_ter.png + +Archivo comprimido cargado + +o si desea descomprimirlo a través de la selección de la opción 'Extraer archivos' en la ventana emergente: + +.. figura:: medios/resource_mng\_5\_quat.png + +Cargar archivo descomprimido + +.. figura:: medios/resource_mng\_3\_bis.png + +Resultado de los archivos descomprimidos cargados + +**Definición de metadatos del modelo** + +Como ya se dijo al principio, **modelos** es la carpeta única administrada tanto por la Community como por enterprise Edition. Contiene todos los modelos de minería de datos utilizables por el Catálogo de funciones de Knowage. + +Para cada modelo es posible definir sus metadatos, descargar y/o eliminar el modelo utilizando directamente las opciones del árbol: + +.. figura:: medios/resource_mng\_8.png + +Opciones de la carpeta Modelos + +*Gestión de metadatos* + +El **Metadatos** abre una interfaz gráfica de usuario en la que el usuario puede definir información de metadatos sobre el modelo en uso. + +Por lo tanto, es posible insertar: + +* un nombre más específico para el modelo +* el número de versión del modelo +* el tipo de análisis: un valor seleccionable entre 'Descriptivo', 'Predictivo' y 'Prescriptivo' +* una imagen para representar la lógica del modelo cargable a través del icono específico +* una descripción detallada +* información sobre la precisión y, a continuación, el rendimiento del modelo +* información sobre la forma de uso del modelo +* Información sobre los formatos de los datos de entrada y salida + +.. figura:: medios/resource_meta\_4.png + +Ejemplo de metadatos diff --git a/functionalities-guide/scorecard/index.es.rst b/functionalities-guide/scorecard/index.es.rst new file mode 100644 index 00000000..994fbd0c --- /dev/null +++ b/functionalities-guide/scorecard/index.es.rst @@ -0,0 +1,97 @@ +# Scorecard + +El **Scorecard** La función, disponible en la suite Knowage como se destaca en la siguiente figura, permite supervisar diferentes KPI al mismo tiempo. Esta opción ofrece una visión general completa exclusiva de la situación de los KPI cuando el usuario no está interesado en una comprobación de umbral único. De hecho, esta herramienta es útil cuando se trata de supervisar la superación de dos o más valores críticos de KPI. + +.. \_scorcardforthecontmenu: +.. figura:: media/image161.png + + Scorecard from the contextual menu. + +## Desarrollo de cuadros de mando + +Un cuadro de mandos está estructurado en niveles jerárquicos. En breve, hay un primer nivel llamado **Perspectiva** compuesto por KPIs agrupados en objetivos. De otra manera **Objetivos** se les asigna un umbral en función de los KPI de los que se componen. A continuación describiremos en detalle una configuración de cuadro de mandos. Al hacer clic en el elemento de menú Cuadro de mandos, se abre la ventana de la figura siguiente. Aquí se enumeran los cuadros de mando implementados y se pueden explorar una vez seleccionados y editados. + +.. \_scorcardwindow: +.. figura:: media/image162.png + + Scorecard window. + +El icono "Plus" disponible en la esquina superior derecha de la página abre una nueva ventana donde establecer un nuevo cuadro de mandos, como se muestra a continuación. Asigne un nombre y haga clic en **Añadir perspectiva** (Figura a continuación). + +.. figura:: media/image163.png + +Definición de un nuevo cuadro de mandos. + +Una perspectiva le permite organizar el monitoreo sobre los objetivos. + +.. figura:: media/image164.png + + Add perspective to the scorecard. + +En la siguiente figura se da un ejemplo. + +.. \_perspectlistexample: +.. figura:: media/image165.png + + Perspective list example. + +De hecho, cada perspectiva gestiona uno o más objetivos de acuerdo con los requisitos del usuario. Un destino consta de uno o más KPI y se le asigna un color umbral según el elegido **Criterio de evaluación**. De hecho, si uno selecciona: + +* **Política "Mayoritaria"** el objetivo obtiene el umbral del umbral de KPI que supera numéricamente a los demás, +* **Política "Mayoría con prioridad"** el objetivo obtiene el umbral de un KPI específico, +* **Política "Prioritaria"** el objetivo obtiene el umbral mayoritario de los KPI en caso de que el KPI primario declarado devuelva el umbral inferior, es decir, el "verde", mientras que obtiene el umbral de un KPI declarado primario en caso de que este último devuelva los otros umbrales, a saber, el "amarillo" o el "rojo". + +.. advertencia:: +**Los umbrales de los KPI seleccionados deben tener los colores correctos** + + Note that the scorecard shows the right colors accordingly with the selected policy only if the KPIs which compose the targets have **no filters** and **standard colors** (see Section 7.1, Step 2 for definitions) to highlight the threshold. + +.. advertencia:: +**Colores "estándar" para umbrales** + + When the targets contain parametric KPIs the target/perspective evaluation cannot be completed for value absence. Therefore the warning lights turn grey. The right visualization of the scorecard must be implemented through a scorecard document. Check Section 8.2 to have more details on how to develop a scorecard document. + +A continuación se muestra un ejemplo. + +.. figura:: media/image166.png + + Select the KPI with priority. + +La misma opción está disponible en el nivel de perspectiva (consulte la siguiente figura), es decir: + +* **Política "Mayoritaria"** la perspectiva obtiene el umbral del umbral objetivo que supera numéricamente a los demás, +* **Política "Mayoría con prioridad"** la perspectiva obtiene el umbral de un objetivo específico, +* **Política "Prioritaria"** la perspectiva obtiene el umbral mayoritario de los objetivos en caso de que el objetivo principal declarado devuelva el umbral inferior, es decir, el "verde", mientras que obtiene el umbral de un objetivo declarado primario en caso de que este último devuelva los otros umbrales, a saber, el "amarillo" o el "rojo". + +.. \_prespectpolicy: +.. figura:: media/image167.png + + Perspective policy. + +Recuerde guardar una vez que se hayan establecido las perspectivas y los objetivos. + +## Creación de un documento de cuadro de mandos + +Una vez guardado, es posible desarrollar un documento de cuadro de mando que puede ser fácilmente consultado por los usuarios finales (autorizados). Para crear un documento de cuadro de mandos, haga clic en el icono "Más" disponible en el navegador de documentos y luego en "Documento genérico" del panel como se muestra a continuación. Aquí rellena + +.. figura:: media/image168.png + + Create a generic document from document browser. + +en los campos obligatorios (marcados con un asterisco) y seleccione el tipo KPI y **Motor KPI**. Luego abra la "Compilación de plantilla". Aquí seleccione la opción "Cuadro de mandos" como en la figura siguiente9 y, en consecuencia, Creación de un documento de cuadro de mandos, elija un cuadro de mandos existente de la lista. Realice las personalizaciones deseadas y guárdelas. + +.. figura:: media/image169.png + + Template creation window. + +La siguiente figura muestra un ejemplo de la interfaz del documento del cuadro de mandos. Las flechas señalan las perspectivas de logro de los objetivos o, por el contrario, la falta de los objetivos. Además, el logro / fracaso de los objetivos individuales se identifica mediante las señales de flecha cerca de cada objetivo. + +.. figura:: media/image170.png + + Scorecard document interface. + +Tenga en cuenta que es posible verificar la política utilizada para cada perspectiva. De hecho, al hacer clic en uno de ellos se abre un asistente que muestra la política adoptada y el objetivo obtenido por ach KPI. + +.. figura:: media/image170.png + + Scorecard document interface. diff --git a/functionalities-guide/svg-document-visualization/index.es.rst b/functionalities-guide/svg-document-visualization/index.es.rst new file mode 100644 index 00000000..ef5d2d68 --- /dev/null +++ b/functionalities-guide/svg-document-visualization/index.es.rst @@ -0,0 +1,512 @@ +# Visualización de documentos SVG + +En este capítulo supondremos que un usuario técnico ha creado un documento SVG y que el usuario final está habilitado para visualizarlo y utilizarlo. Puede elegir qué KPI mostrar en el "mapa" y analizar sus valores, luego podría profundizar en los submiembros u otros documentos de Knowage para ver otros detalles y otros análisis. + +.. figura:: media/image241.png + + SVG document visualization example. + +Las imágenes de la figura anterior muestran cómo es posible cambiar el análisis de KPI y profundizar hacia otros documentos SVG de la misma jerarquía. + +## Mi primer mapa o diseño SVG + +El SVG Viewer Engine es una herramienta que permite desarrollar documentos basados en el formato SVG, acrónimo de Scalable Vector Graphics. Permite mostrar información comercial diferente directamente en cada área y permite la acción de perforación a otros archivos SVG más detallados utilizando una jerarquía lógica. Este visor se divide en dos secciones: + +* un panel con muchos detalles dinámicos como medidas, capas y leyenda, además de una sección opcional con información específica sobre el + documento activo, +* el documento svg. + +Por poner un ejemplo, podemos imaginar visualizar a través de un SVG el mapa usa. Al principio podemos mostrar datos a nivel de "Regiones" y luego a través del clic / taladro - mostrar la misma u otra información en el "nivel" de los Estados. Damos un ejemplo de documento de mapa producido con el motor SVG en las dos figuras a continuación. + +.. \_svgexampleusalevel: +.. figura:: media/image243.png + + SVG document example at the USA Regions level. + +.. figura:: media/image244.png + + SVG document example at the States level after the selection of the “Center West” Region. + +Al igual que otros tipos de documentos knowage hay un conjunto de actividades gestionadas por los usuarios técnicos y otras utilizadas por los usuarios finales. Estos últimos son específicamente sobre consultoría. + +Actividades técnicas + +``` + +First of all, a technical user needs to configure the logical hierarchy of the SVG and to define datasets with the business data he/she wishes to show. Finally he/she must type the document template. We will give details about these points in the following sections. + +SVG Catalogue +^^^^^^^^^^^^^^ + +The first activity that you need to do as administrator is to find or create an SVG file. Any file saved in SVG format is a text file in XML format. As a consequence, they can easily be queried, indexed, enriched with scripts and, if necessary, zipped. The SVG final output could represent everything: geographical areas (like USA in the previous example), concepts (like the item production steps) and so on. + +SVG Format +^^^^^^^^^^^^^^ + +The Scalable Vector Graphics, SVG, refers to an XML-based encoding format, used to describe two dimensional vector graphical objects. SVG is an open standard, defined by the World Wide Web Consortium (W3C), which released its first version in 1999. Read more at http://www.w3.org/Graphics/SVG/ . + +Not all graphical objects of an SVG can be thematized. Using the SVG grouping operator , the developer can create one or more subsets of graphical objects and specify which groups should be subject to thematization. Each group has an unique name, corresponding to the value of the id attribute of the tag (e.g. ). Considering that, graphical objects grouped in an SVG file are usually homogeneous elements (in other words, they model a same category of objects: regions, towns, streets, etc.), we can consider these groups as layers and the objects can be considered as features. + +Once obtained the SVG file, you should register it into Knowage SVG catalogue. + +The Svg catalogue contains all SVG that can be used with this engine throught specific hierarchies. In this context a hierarchy is a definition of three concepts: + +- the hierarchy itself, +- the level, +- the member. + +These three information are used from the system to recover the correct SVG into the catalogue. + +.. _enteringhierarchydet: +.. figure:: media/image245.png + + Entering the hierarchy details. + +As you can see in the figure above, you must insert a name and an optional description of the new SVG component, then you need to specify a logical hierarchy’s label, its number of the level and a logical name for the member that it represents. At last you need to upload the SVG file. When this configuration will be saved, the system will read the SVG content and for each group (or tag ) will be created a layer. All layers will be shown into the “Feature Detail” section (read only section). + +In this first example in the figure above we defined an SVG component for the USA regions specifying that it’s the first level (in other words it’s the first SVG of the “USA” hierarchy). + +The second level (the more detailed SVG) is about the USA states and it’s defined like the next example below: + +.. figure:: media/image246.png + + Entering the hierarchy details. + +As you can see the principal differences between these configurations are only about the level content and the member label. This means that both will be used in the same hierarchy’s context and that from the “Regions” SVG will be possible to drill on the “States” SVG. Anyway it is not mandatory to define more than one level: it depends from each project implementation. + +Datasets definition +^^^^^^^^^^^^^^^^^^^^^ + +After that all SVG was loaded, you must define a dataset (one for each level) that you want to use for getting and showing business information from your DWH. You can refer to Chapter 3 of this manual to know how to create datasets. Here in the following figure a dataset of our example: + +.. figure:: media/image24748.png + + Left. Dataset behind the SVG document. Right. Dataset preview. + +Template building +^^^^^^^^^^^^^^^^^^^^ + +The template allows the SVG viewer to properly join business data (Knowage dataset) and spatial data (SVG included in the catalog), in order to produce the analytical documents. + +At the moment there is not yet a designer to create a template for this engine, anyway, it’s an XML file very simple to define. + +An example below. + +.. code-block:: xml + :linenos: + :caption: Example of SVG code for template file. + + + + + + + + + + +Basically, it’s necessary to specify the hierarchy that we want to use, as well as its members (remember that with member we are considering a specific SVG). + +We recap the meaning of the main tag in the next table *Recap of properties and function*. + +After, we need to define each member and first of all we can note that is composed by three sections: METADATA, LAYERS and MEASURE, as in Code below: + +.. code-block:: xml + :linenos: + :caption: Example of SVG code for template file. + + + + + + + +Let us see each of them in more depth. + +- **METADATA.** This is the section where we define the dataset metadata, in fact, each COLUMN tag defines the dataset columns that we want to use as attribute, as measure (used for thematize the SVG) or other technical meaning usefull for the engine. + +.. code-block:: xml + :linenos: + :caption: Example of SVG code for template file. + + + + + + + + + +Once again we give some details on metadata in next table. + +- **LAYERS.** In this section we define all layers that we want to enable in the document. Each layer will be shown into the detail panel “Layers section” as you can see in figure below and could be actived or disactived directly by an action of the the final user. At least one layer must be defined. + + .. figure:: media/image249.png + + Available layers set by a technical user. + +.. code-block:: xml + :linenos: + :caption: Code relative to the LAYER setting. + + + + + + +.. _recaptagproperties: +.. table:: Recap of properties and function. + :widths: auto + + +-----------------------+-----------------------+-----------------------+ + | Tag | Property | Note | + +=======================+=======================+=======================+ + | HIERARCHY | name | Mandatory. The name | + | | | of the hierarchy that | + | | | we want use. The name | + | | | must match to an | + | | | existing hierarchy | + | | | into the SVG | + | | | catalogue. | + +-----------------------+-----------------------+-----------------------+ + | MEMBER | name | Mandatory. The name | + | | | of the member that we | + | | | want use. The name | + | | | must match to an | + | | | existing member for | + | | | the hierarchy | + | | | specified into the | + | | | SVG catalogue. Is too | + | | | possibile get its | + | | | value dinamically | + | | | throught an | + | | | analytical driver by | + | | | using the standard | + | | | syntax | + | | | | + | | | $P | + +-----------------------+-----------------------+-----------------------+ + | MEMBER | measure_dataset | Mandatory. The label | + | | | of the dataset | + | | | defined in Knowage | + | | | Dataset | + | | | configuration. | + +-----------------------+-----------------------+-----------------------+ + | MEMBER | level | Mandatory. The number | + | | | of the level. This | + | | | value must match the | + | | | level property into | + | | | the catalogue for the | + | | | hierarchy and the | + | | | member specified. | + +-----------------------+-----------------------+-----------------------+ + | COLUMN | TYPE | Mandatory. The type | + | | | of the specific | + | | | column. Possible | + | | | values are: | + | | | | + | | | - **geoid**: | + | | | mandatory. The | + | | | engine uses this | + | | | column to join the | + | | | dataset records | + | | | and the | + | | | corresponding | + | | | features in the | + | | | svg. Also, it’s | + | | | the default value | + | | | passed within the | + | | | drill action to | + | | | the svg of lower | + | | | level | + | | | (alternatively to | + | | | the drillid | + | | | property). | + | | | | + | | | - **measure**: | + | | | mandatory. Defines | + | | | the column like | + | | | measure. All | + | | | measures defined | + | | | in this section | + | | | will be shown into | + | | | the detail panel | + | | | (Measure section). | + | | | | + | | | - **drillid**: | + | | | optional. Defines | + | | | the alternative | + | | | value to pass | + | | | within the drill | + | | | action to the next | + | | | svg | + | | | | + | | | - **parentid**: | + | | | optional. Defines | + | | | the column that | + | | | the system need to | + | | | use for get | + | | | correctly data | + | | | linked to the | + | | | parent value | + | | | selected. | + | | | | + | | | - **crosstype**: | + | | | optional. Defines | + | | | the column that | + | | | set the cross | + | | | navigation type. | + | | | Possible values | + | | | are “cross” for | + | | | external | + | | | navigation or | + | | | “drill” for | + | | | internal | + | | | navigation. If the | + | | | single element | + | | | returns null the | + | | | link will be | + | | | disabled | + | | | | + | | | - **visibility**: | + | | | optional. Defines | + | | | the column that | + | | | throught a boolean | + | | | value (string with | + | | | “true” / “false”) | + | | | guides the | + | | | visibility of each | + | | | svg element. | + | | | | + | | | - **label**: | + | | | optional. Defines | + | | | the column with | + | | | dynamic label to | + | | | show on each svg | + | | | element. | + | | | | + | | | - **info**: | + | | | optional. Defines | + | | | the column that | + | | | contain a static | + | | | detail to show on | + | | | the Info section | + | | | into the detail | + | | | panel. | + | | | | + | | | - **tooltip**: | + | | | optional. Defines | + | | | the column that | + | | | contains a text | + | | | (also html) to be | + | | | showned in the | + | | | tooltip on mouse | + | | | hover. | + +-----------------------+-----------------------+-----------------------+ + | COLUMN | column_id | The dataset label | + | | | that we want to use | + | | | in according to the | + | | | previous type | + | | | setting. | + +-----------------------+-----------------------+-----------------------+ + | LAYER | name | Mandatory. The layer | + | | | name. Mandatory. It | + | | | must exists into the | + | | | SVG | + | | | document/catalogue | + | | | (as tag + + + + + + + + + + + + +We report the next table for further details on THRESHOLDS and COLOURS tag. This table includes the heuristics supporting value interval partition into a finite number of subintervals (type attribute of the THRESHOLDS tag). + +While the following table defines the heuristics supporting color definition for each value sub-interval (type attribute of the COLOURS tag). + +Sometimes users need to color the map and, at the same time, to continue to see the underlying objects, through a transparency effect (e.g. a raster image). In this case, specify the opacity parameter in order to properly regulate the transparency level of colors (1 = no transparency; 0 = invisible). + +Now, after the template definiton, you can create it into Knowage. Remember that it must be a “Location Intelligence” document type with the engine “SVG Viewer Engine”. + +.. _recaplayerproperties4: +.. table:: Recap of layer tag properties and function. + :widths: auto + + +-----------------------+-----------------------+----------------------------------------------------------------+ + | Tag | Property | Note | + +=======================+=======================+================================================================+ + | MEASURES | default_kpi | Mandatory. Defines the default kpi or the kpi that we wont | + | | | enable at the beginning, when we start the document | + | | | execution. Its value must exist into the METADATA section as | + | | | measuere type. | + +-----------------------+-----------------------+----------------------------------------------------------------+ + | KPI | column_id | Mandatory. The column_id property the measure that you | + | | | are defining. Its value must exist into the METADATA section | + | | | as measure type. | + +-----------------------+-----------------------+----------------------------------------------------------------+ + | KPI | Description | Mandatory. The label that you want show into the detail panel. | + +-----------------------+-----------------------+----------------------------------------------------------------+ + | THRESHOLDS | type | Mandatory. The type of logic to use to define the | + | | | thematization. It could be: | + | | | | + | | | - **quantile**: it partitions the interval into N quintiles. | + | | | | + | | | - **perc**: it partitions the interval into subintervals | + | | | whose extent represents a specific fraction of the overall | + | | | interval extent. | + | | | | + | | | - **uniform**: it partitions the interval into N subintervals | + | | | of a same extent. | + | | | | + | | | - **static**: it partitions the interval into smaller | + | | | fixed-size subintervals, statically defined by the RANGE | + | | | parameter | + | | | | + +-----------------------+-----------------------+----------------------------------------------------------------+ + | THRESHOLDS | lb_value | Mandatory. The lower value outside of which no value is | + | | | considered. | + +-----------------------+-----------------------+----------------------------------------------------------------+ + | THRESHOLDS | ub_value | Mandatory. The upper value outside of which no value is | + | | | considered. | + +-----------------------+-----------------------+----------------------------------------------------------------+ + | PARAM | name | Mandatory. Specify the parameter value necessaty to define | + | | | correctly the temhatization. Its value depends by the | + | | | threshold type. | + | | | | + | | | This attribite could be present more than once. | + +-----------------------+-----------------------+----------------------------------------------------------------+ + | PARAM | value | Mandatory. It’s the parameter name value. | + +-----------------------+-----------------------+----------------------------------------------------------------+ + | PARAM | label | Optional. Specify the static labels for the legend when | + | | | thresholds type is “static”. | + +-----------------------+-----------------------+----------------------------------------------------------------+ + | PARAM | value | Optional. It’s the parameter label value. | + +-----------------------+-----------------------+----------------------------------------------------------------+ + | COLOURS | type | Mandatory. Specify the logic type for defining colors range. | + | | | It could be: | + | | | | + | | | - **static**: it assigns each sub-interval a specific color | + | | | that is statically defined. | + | | | | + | | | - grad: it assigns each sub-interval a specific color that is | + | | | dynamically calculated through a gradient function. | + +-----------------------+-----------------------+----------------------------------------------------------------+ + | COLOURS | outboud_color | Mandatory. Defines the color to use when the value for the | + | | | specific area is outbound of the maximum range.165 | + +-----------------------+-----------------------+----------------------------------------------------------------+ + | COLOURS | null_values_color | Mandatory. Defines the color to use when the value for the | + | | | specific area is null | + +-----------------------+-----------------------+----------------------------------------------------------------+ + | PARAM | name | See the PARAM\ name property specified for the THRESHOLD tag | + +-----------------------+-----------------------+----------------------------------------------------------------+ + | PARAM | value | See the PARAM\ value property specified for the THRESHOLD tag | + +-----------------------+-----------------------+----------------------------------------------------------------+ + | type | static | It partitions the interval into smaller fixed-size | + | | | subintervals, statically defined by the RANGE parameter | + | | | | + | | | | + | | | | + | | | | + | | | | + | | | | + | | | | + +-----------------------+-----------------------+----------------------------------------------------------------+ + | type | quantile | it partitions the interval into N quintiles. The exact | + | | | amount of quintiles to be created is defined by the | + | | | GROUPS_NUMBER parameter: | + | | | | + | | | | + | | | | + | | | | + | | | | + +-----------------------+-----------------------+----------------------------------------------------------------+ + | type | perc | it partitions the interval into subintervals whose | + | | | extent represents a specific fraction of the overall interval | + | | | extent. The extent of each single subinterval is | + | | | defined by the RANGE parameter. | + | | | | + | | | | + | | | | + | | | | + +-----------------------+-----------------------+----------------------------------------------------------------+ + | type | uniform | it partitions the interval into N subintervals of a same | + | | | extent. The exact number of sub-intervals is defined by the | + | | | GROUPS_NUMBER parameter. | + | | | | + | | | | + | | | | + | | | | + | | | | + +-----------------------+-----------------------+----------------------------------------------------------------+ + | type | static | Static: it assigns each sub-interval a specific color that | + | | | is statically defined, through the RANGE parameter | + | | | | + | | | | + | | | | + | | | | + +-----------------------+-----------------------+----------------------------------------------------------------+ + | type | grad | Gradient : it assigns each sub-interval a specific color that | + | | | is dynamically calculated through a gradient function, | + | | | which progressively scales the base color intensity. This is | + | | | defined through the BASE_COLOR parameter | + | | | | + | | | | + | | | | + | | | | + +-----------------------+-----------------------+----------------------------------------------------------------+ + +Advanced functionalities +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Other the default drill navigation that you have if for the document are defined more than one member, is it possible to cross versus other Knowage documents. To enable this feature, is necessary to set the enableExternalCross property for the MEMBER tag. Here an example: + +.. _codeforenablingcross: +.. code-block:: xml + :linenos: + :caption: Code for enabling external cross navigation. + + + + +With this setting, you are able to create a “Cross Navigation Definition” with the standard Knowage functionality, where for default you’ll find the element_id as outuput parameter as shown in figure below. It means that the identifer of the area selected is able to be passed. Other default output parameters are **Hierarchy**, **Member** and **Level**. + +.. figure:: media/image252.png + + Using the Cross Navigation definition to link to external documents. + +In a cross navigation it is also possible to pass the dataset column values. It is only necessary that a technical user prepares specific output parameters, setting the name like the alias of the dataset columns. + +``` diff --git a/functionalities-guide/what-if-analysis/index.es.rst b/functionalities-guide/what-if-analysis/index.es.rst new file mode 100644 index 00000000..bbe78838 --- /dev/null +++ b/functionalities-guide/what-if-analysis/index.es.rst @@ -0,0 +1,304 @@ +# Análisis hipotético + +El **¿Qué pasaría si** El análisis es la capacidad de hacer hipótesis y ver cómo estos impactan en el negocio. En la práctica, el usuario puede realizar un análisis hipotético utilizando una extensión de la herramienta OLAP. El proceso de What-if se compone en tres fases: + +* preparación de datos, +* definición de flujo de trabajo, +* definición de hipótesis. + +Comenzamos entonces a centrarnos en esta última fase. + +## Detalles de la interfaz + +El flujo de trabajo tiene un impacto en la visualización de datos. Un usuario puede comprender el estado del flujo de trabajo mirando la sección Qué pasaría si de la barra lateral. Hay tres posibilidades descritas a continuación. + +* El usuario puede realizar el análisis What-if: en este caso la sección What-If contiene los botones para editar valores; vea la figura a continuación para + marque esos botones. + +.. figura:: media/image213.png + + What-If buttons inside the sidebar. + +* El esquema está bloqueado por otro usuario. En este caso, aparece un mensaje con el nombre del usuario activo en el flujo de trabajo como se muestra a continuación. + +.. figura:: media/image214.png + + The What-If is used by another user. + +* El flujo de trabajo ha finalizado. + +.. figura:: media/image215.png + + The What-If is finished. + +Recordamos brevemente la funcionalidad de los botones principales: + +* Modelo de desbloqueo: cambia el estado del flujo de trabajo para mover el control al siguiente usuario. +* Guardar: persiste la modificación en la base de datos. +* Guardar como nueva versión: persiste la modificación en la base de datos en una nueva versión. +* Deshacer: deshace la última modificación. +* Eliminar versiones: abre un asistente que el usuario puede usar para eliminar versiones. +* Asistente de salida: permite al usuario exportar el cubo de edición en dos formatos diferentes, tabla y csv en el específico. + +## Descripción del metalenguaje + +Vimos que el motor What-If permite al usuario final cambiar los valores de los datos. Aquí vemos cómo es posible modificar un valor de celda a través de una fórmula, incondicionalmente a partir del nivel de agregación de la celda. La fórmula debe escribirse utilizando un lenguaje particular llamado **meta-lenguaje** que se describe a continuación. En primer lugar, los símbolos aritméticos disponibles son: + - :sub:`\*` / ( ) %. + +El cálculo 100 + 10% es un ejemplo simple de uso de la operación %. Tenga en cuenta que la fórmula puede comenzar con "=", pero esto no es obligatorio. + +Para activar la edición de una celda de medida que no se muestra en el OLAP primero debe hacer clic en el icono de filtro de la tarjeta de filtro de medida y verificar la medida de destino. A continuación, seleccione la versión que desea utilizar y cambie los valores de la figura a continuación muestra dónde están disponibles estos objetos en la interfaz. + +.. figura:: media/image21616.png + + Checking measures and selecting version. + +Luego haga doble clic en la celda de medida de destino y aparecerá un cuadro que le permitirá insertar una fórmula. Escriba la sintaxis de cálculo y haga clic en el botón *f*\ (*x*) para convalidarlo o cancelarlo, como se muestra a continuación. + +.. figura:: media/image21819.png + + Inserting formula and its convalidation. + +Destacamos que también se puede hacer referencia a miembros que no están incluidos en la tupla representada por la celda que se va a modificar. Veamos algunos ejemplos. Por ejemplo, supongamos que la celda se refiere a la siguiente tupla informada en el código siguiente: + +.. code-block:: xml +:linenos: +:caption: Producto.Deli + + [Measures].[Store Sales], [Product].[Food].[Deli], [Version].[0], + [Region].[Mexico Central], [Customers].[All Customers], [Customers].[All Customers] + +Puede referirse a la tupla en el siguiente código con solo Product.Eggs y al mismo tiempo a la tupla en el segundo código a continuación con solo Product.Eggs; Medidas.Ventas de unidades + +.. \_producteggs: +.. code-block:: xml +:linenos: +:caption: Producto.Huevos + + [Measures].[Store Sales], [Product].[Food].[Eggs], [Version].[0], + [Region].[Mexico Central], [Customers].[All Customers], [Customers].[All Customers] + +.. code-block:: xml +:linenos: +:caption: Producto.Huevos; Medidas.Ventas de unidades + + [Measures].[Unit Sales], [Product].[Food].[Eggs], [Version].[0], + [Region].[Mexico Central], [Customers].[All Customers], [Customers].[All Customers] + +Tenga en cuenta que si crea una fórmula en una celda y desea moverla a lo largo de una dimensión (por ejemplo, la celda hace referencia al miembro Time.2016 y desea obtener un valor para Time.2017), debe hacer referencia a un miembro del mismo nivel. Así, por ejemplo, puede obtener el valor de la celda para Time.2017, pero no para Time.2017.May. + +La sintaxis es como la que se muestra en Referencia a diferentes miembros o, en caso de que esté utilizando otra jerarquía, como en el segundo código a continuación donde puede concatenar diferentes miembros con ";". + +.. code-block:: xml +:linenos: +:caption: Refiriéndose a diferentes miembros. + + .or[].[] + +.. \_referringdiffmembers: +.. code-block:: xml +:linenos: +:caption: Se refiere a diferentes miembros de otra jerarquía. + + ..or[].[< hierarchy's name>].[] + +También puede referirse a miembros que están en el mismo nivel pero que no son miembros hermanos: +supongamos que, por ejemplo, la tupla de la celda es como en el código siguiente: + +.. code-block:: xml +:linenos: +:caption: Ejemplo de tupla de celda. + + [Measures].[Store Sales], [Product].[Food].[Deli], [Version].[0], + [Region].[Mexico Central], [Customers].[All Customers], [Customers].[All Customers] + +Tenga en cuenta que puede consultar la tupla + +.. code-block:: xml +:linenos: +:caption: Ejemplo de tupla de celda. + + [Measures].[Store Sales], [Product].[Drink].[Alcoholic Beverages], + [Version].[0], [Region].[Mexico Central], [Customers].[All Customers], + [Customers].[All Customers] + +solo con: + +.. code-block:: xml +:linenos: +:caption: Acortar el código de sintaxis. + + [Product].[Drink.Alcoholic Beverages] + +Otro ejemplo de Code a continuación + +.. code-block:: xml +:linenos: +:caption: Ejemplo de tupla de celda. + + [Measures].[Store Sales], [Product].[Food].[Deli].[Meat], + [Version].[0], [Region].[Mexico Central], [Customers].[All Customers], + +al código a continuación + +.. code-block:: xml +:linenos: +:caption: Ejemplo de tupla de celda. + + [Measures].[Store Sales], [Product].[Drink].[Alcoholic Beverages].[Beer and Wine], [Version].[0], + [Region].[Mexico Central], [Customers].[AllCustomers], [Customers].[All Customers] + +es como en el código siguiente + +.. code-block:: xml +:linenos: +:caption: Expresión usada. + + [Product].[Drink.Alcoholic Beverages.Beer and Wine] + +Tenga en cuenta que la última parte de la expresión es la parte de la ruta de acceso al miembro de destino que difiere de la ruta de acceso del miembro de la celda. Algunos otros ejemplos: + +.. code-block:: xml +:linenos: +:caption: Otro ejemplo. + + [Product].[Food] + +## Implementación de análisis hipotéticos + +En este capítulo trataremos algunas características técnicas del análisis What-If que solo pueden ser manejadas por usuarios expertos. + +Descripción del flujo de trabajo\* + +``` + +When you perform a what-if analysis the schema is shared in order to be used as a data source. Therefore each time a document linked to a schema can be edited only by one user per time. This behaviour is managed by the Workflow of the schema. The administrator can configure a workflow opening the details of the model in OLAP schema catalogue, selecting the schema and going on the workflow tab available on the top of the right sided area. The tab is red circled below. + +.. figure:: media/image220.png + + Workflow tab. + +Referring to the next figure, the interface for the definition of the workflow is composed of a double list where + +- the **available users** area contains all the users, +- the **workflow** area contains the sequence of users for the workflow. + +.. _workflowtabinterf: +.. figure:: media/image221.png + + Workflow tab interface. + +When an administrator clicks on the user in the list “available users” the user will be added in the workflow as shown in Figure 10.3. + +Administrator can move the users in the sequence or remove them clicking on the “action buttons”. When the workflow is defined, the administrator can start it clicking on the button start. To start a workflow means to enable the first user of the sequence to apply the what-if on that schema. When a workflow is started it can not be edited by anyone else and an icon appears in the row of actual active user so that the administrators can monitor the state of the schema. An example is provided by Figure 10.4 + +Schema definition\* +``` + +Como dijimos anteriormente, el análisis What-If requiere alguna modificación en la base de datos. El primer paso es crear una nueva tabla en la base de datos para almacenar la versión con nombre de los datos modificados. A continuación, el usuario cambiará los valores del cubo; a continuación, es obligatorio crear una nueva tabla con una estructura similar al cubo analizado y una nueva tabla (wbversion) que contendrá el control de versiones de las definiciones establecidas en el análisis. + +Por lo tanto, la estructura de la nueva tabla de hechos debe contener: + +* todas las claves externas de las cotas (todas las visibles en el cubo), + +.. figura:: media/image222.png + + Selecting users for workflows. + +.. figura:: media/image223.png + + Selecting users for workflows. + +* todas las medidas editables, +* una nueva columna numérica que es una clave externa que hace referencia a la tabla de versiones. + +En la figura siguiente, hay un ejemplo en el que se sales_fact\_1998 el cubo y se sales_fact\_1998\_virtual la nueva tabla. + +.. figura:: media/image224.png + + Cube and new virtual table example. + +La tabla sales_fact\_1998\_virtual debe inicializarse con los mismos datos contenidos en sales_fact\_1998 más 0 que la versión; la tabla wbversion debe inicializarse con un registro con wbversion = 0 y un nombre más una descripción para los "valores originales". + +Cambios en el esquema mondrian\* + +``` + +Now you should map the new tables in the mondrian schema. In order to merge the fact table and the table with the editable measure we create a virtual cube. A virtual cube is a special cube where the values are the result of the join of other cubes. In our case the join keys are the dimensions. The actions to be performed in the mondrian schema are listed right below. + +- To create a new "Version" dimension as inChanging the Mondrian Schema. + +.. code-block:: xml + :linenos: + :caption: Changing the Mondrian Schema. + + + +
+ + + + +- To create the mapping of the editable cube (in our example the table sales_fact_1998_virtual) as shown in Code Creating the mapping of the editable cube. + +.. code-block:: xml + :linenos: + :caption: Creating the mapping of the editable cube. + + +
+ + + + + + + +The name of the cube ("Sales_Edit") is the value of the edit Cube attribute of the tag scenario in the template. Note that the name of the dimension Version must be exactly "Version"!! + +• To create the virtual cube that will contain the mapping of the columns as in Code below. + +.. code-block:: xml + :linenos: + :caption: Creating the virtual cube. + + + + + + + + + + + + + + + + + + + + + VALIDMEASURE([Measures].[Sales Count Original]) + + + + VALIDMEASURE([Measures].[Unit Sales Original]) + + + +Specifically, in the virtual cube you should specify: + +- the list of cubes to be joined (CubeUsages); +- the list of the dimensions of the cube (as you can see it contains all the common dimensions, plus the Version that belongs only to the editable cube); +- the list of the measures. You can perceive that there is a calculated member for the measure Sales Count Original (Sales Count Original is the name of a measure in the Sales cube). This is a trick for the not editable measures. This type of measure lives only in the DWH cube and not in the editable cube. This is due to the fact that the engine doesnt know how to give a value for these measures for the different values of the Version dimension (remember that only the editable cube has the Version dimension). The calculated field solve this problem propagating the same version of the not editable (and versionable) measure for all the version. + +Now all the MDX queries can be performed in the virtual cube. +``` diff --git a/functionalities-guide/widget-gallery/index.es.rst b/functionalities-guide/widget-gallery/index.es.rst new file mode 100644 index 00000000..ab490945 --- /dev/null +++ b/functionalities-guide/widget-gallery/index.es.rst @@ -0,0 +1,81 @@ +# Galería de widgets + +El **Galería de widgets** es una funcionalidad disponible desde la versión 8.0 que permite a los usuarios y editores crear una plantilla y compartirla en varios paneles. +Al crear una plantilla y luego usarla dentro de un panel, los usuarios tendrán la capacidad de crear elementos complejos del panel de control de manera bastante fácil y rápida, manteniendo una plantilla base común. + +Esta funcionalidad está disponible para: + +* Widget HTML +* Widget gráfico personalizado +* Widget de Python + +El primer paso es crear una galería de plantillas o subir alguna plantilla. + +## Gestión de galerías + +Dentro del panel de administrador debe aparecer un nuevo elemento denominado **Gestión de galerías**. +Este enlace lo llevará a la administración de la galería, la galería de creación de plantillas de widgets. + +.. figura:: media/image2.png + + Gallery management example. + +En la parte izquierda de la interfaz está disponible la lista de las plantillas de widgets. Al principio, esta sección probablemente estará vacía. + +Hay dos formas de agregar nuevas plantillas: + +* Agregar una nueva plantilla +* importar una plantilla + +Si está agregando una nueva plantilla, verá la sección de detalles a la derecha y tendrá la posibilidad de crear una plantilla. + +Usando la importación verá un cuadro de diálogo para elegir la plantilla a importar. Al hacer clic en "importar", se agregará a la lista actual. + +Un **Plantilla** es un archivo json que contiene una colección de propiedades que describen el widget y el código que lo compondrá. + +Estarán presentes los siguientes campos: + +* **Nombre**: Obligatorio. El nombre de la plantilla de widget +* **Tipo**: Obligatorio. El tipo de widget. +* **Tipo de salida**: Disponible solo para el widget de Python. Establecerá el tipo de salida del código python. +* **Descripción**: Opcional. La descripción de la plantilla de widget será visible como información sobre herramientas en la selección del panel. +* **Etiquetas**: Opcional. Una lista de etiquetas únicas para categorizar fácilmente las plantillas. También es posible buscar usando etiquetas. Los valores permitidos para las etiquetas son letras mayúsculas y minúsculas, números, '-', '\_'. El carácter de espacio no está permitido. +* **Imagen**: Opcional. La imagen del widget que se mostrará en la selección del panel. El tamaño máximo de la imagen es de 200k. +* **Sección de código**: Obligatorio. El editor de código. + +Dependiendo del tipo de widget seleccionado, los editores disponibles cambiarán de esta manera: + +* **Widget HTML**: Editores HTML, CSS +* **Widget de gráfico personalizado**: Editor HTML, CSS y JS +* **Widget de Python**: Editor de código Python + +.. figura:: media/image1.png + + Selected widget template. + +Para guardar la plantilla, es posible hacer clic en la barra de herramientas superior derecha en el *salvar* botón. Si el botón Guardar está deshabilitado, uno o más campos obligatorios están vacíos o no son válidos. +También es posible exportar la única plantilla seleccionada o simplemente cerrar la página y elegir otra. + +.. figura:: media/image3.png + + Toolbar icons. + +## Galería de paneles + +Dentro de la funcionalidad de la cabina o del tablero, una nueva pestaña estará presente al crear un nuevo widget de los tipos disponibles. + +.. figura:: media/image4.png + + New widget templates list. + +Esta pestaña no estará disponible cuando no se defina ninguna plantilla y si el widget se abre después de que se guarde por primera vez. + +La primera plantilla siempre será la "vacía", para permitir a los usuarios crear un widget personalizado sin partir de una plantilla. +Las otras plantillas estarán disponibles después de la vacía y mostrarán la imagen, las etiquetas establecidas por el editor y, al pasar el cursor, la descripción de la plantilla. + +Al hacer clic en un elemento, el código establecido en la administración de la galería se copiará en la nueva plantilla de widget, preparando el widget para las personalizaciones definitivas. +El usuario solo tendrá que vincular datos dinámicos o cambiar la sección css específica para crear el widget deseado. + +.. figura:: media/image5.png + + Selected template editor.