Saltar al contenido principal
Version: próxima

awe-104 Recuperación y manipulación de datos

This tutorial explains the main AWE data flow: where screen data comes from, how you shape server-side retrieval, and how you persist changes. Start with enumerated values and queries, then add maintains, and only after that move into advanced integrations such as email, queues, or service-backed retrieval.

Quick path​

  1. Use an enumerated when the list is small and stable.
  2. Use variables to bind screen values into queries or maintains.
  3. Use Queries.xml to retrieve data.
  4. Use Maintain.xml to insert, update, or delete data.
  5. Treat email, queues, and service-backed flows as advanced extensions.

Before you start​

This page pairs well with:

  • awe-103 for criteria, grids, and charts
  • awe-107 for Java and service-backed logic

Keep the high-level model in mind:

screen criteria -> variables -> query or service -> grid/chart/value
screen action -> maintain or service -> database or side effect

Step 1: Use enumerated values for simple option lists​

Enumerated groups are a good fit for stable key/value lists such as Yes/No flags, language lists, or small internal option sets.

They live in global/Enumerated.xml.

<?xml version="1.0" encoding="UTF-8"?>
<enumerated xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:noNamespaceSchemaLocation="https://aweframework.gitlab.io/awe/docs/schemas/enumerated.xsd">

  <group id="[Group Id]">
    <option label="[Option label]" value="[Option value]" />
    <option label="[Option label]" value="[Option value]" />
  </group>
</enumerated>

First example​

<?xml version="1.0" encoding="UTF-8"?>
<enumerated xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:noNamespaceSchemaLocation="https://aweframework.gitlab.io/awe/docs/schemas/enumerated.xsd">
  <!-- Enumerated YES (0) | NO (1) -->
  <group id="Es1Es0">
    <option label="ENUM_NO" value="0" />
    <option label="ENUM_YES" value="1" />
  </group>
</enumerated>

Use it from a criterion like this:

<criteria label="PARAMETER_ACTIVE" component="select" id="CrtSta" initial-load="enum" target-action="Es1Es0" style="col-xs-6 col-sm-3 col-lg-2" optional="true" />
Select component

Another typical example:

<group id="LanUsr">
  <option label="ENUM_LAN_ES" value="es-ES"/>
  <option label="ENUM_LAN_EN" value="en-GB"/>
  <option label="ENUM_LAN_FR" value="fr-FR"/>
</group>

Step 2: Use variables to bind screen data to the server​

Variables are the bridge between what the user sees on the screen and what your query, maintain, or service needs on the server side.

Typical uses:

  • pass a criterion value into a where clause
  • pass a selected id into an update or delete operation
  • pass a fixed or derived value into a service or maintain

If the screen is the UI layer, variables are the named pipes that carry values into the backend descriptors.

Step 3: Retrieve data with queries​

Database queries are defined in global/Queries.xml. In AWE, a query is a server-side data retrieval definition used by components such as grids, selects, suggests, and charts.

Do not confuse the AWE query descriptor with raw handwritten SQL. AWE translates the XML model for you.

Basic query example​

<query id="CheckAdeudoId">
  <field id="Id" transform="NUMBER" pattern="###" />
  <field id="Id_File" />
  <table id="Adeudo" />
  <where>
    <and>
      <filter left-field="Id_File" condition="eq" right-variable="varIdFile" trim="true" />
    </and>
  </where>
  <variable type="STRING" id="varIdFile" name="idFile" />
</query>

This example shows the normal pattern:

  • define the fields to retrieve
  • define the source table
  • add a where clause
  • bind one or more variables

select and select-multiple​

When a query fills a select-style criterion, the returned fields must follow the expected naming contract:

  • value: the submitted value
  • label: the text shown to the user
<criteria label="PARAMETER_SELECT" id="select" variable="select" component="select"
          initial-load="query" target-action="FillSelect" optional="true"/>
<query id="FillSelect">
  <table id="MyTable"/>
  <field id="field1" alias="value" />
  <field id="field2" alias="label" />
  <where>
    <and>
      ...
    </and>
  </where>
</query>
important

If a criterion loads from a query during screen creation, make sure the query does not depend on variables that only exist after the current screen is already rendered.

suggest and suggest-multiple​

Suggest components use the same label/value field contract, but they retrieve values on demand as the user types.

<criteria label="PARAMETER_SUGGEST" id="suggest" variable="suggest" component="suggest"
          server-action="data" target-action="FillSuggest"/>
<query id="FillSuggest">
  <table id="MyTable"/>
  <field id="field1" alias="value" />
  <field id="field2" alias="label" />
  <where>
    <and>
      <filter left-field="field2" condition="like" right-variable="suggest" ignorecase="true" />
    </and>
  </where>
  <variable id="suggest" type="STRINGB" name="suggest"/>
</query>

Step 4: Persist changes with maintains​

Maintains define write operations in global/Maintain.xml: inserts, updates, deletes, and batched write flows.

Insert example​

<target name="ProNew">
  <insert audit="HISAwePro">
    <table id="AwePro" />
    <field id="IdePro" sequence="ProKey" />
    <field id="Acr" variable="Acr" />
    <field id="Nam" variable="Nam" />
    <field id="IdeThm" variable="IdeThm" />
    <field id="ScrIni" variable="ScrIni" />
    <field id="Res" variable="Res" />
    <field id="Act" variable="Act" />
    <variable id="Acr" type="STRINGN" name="Acr" />
    <variable id="Nam" type="STRINGN" name="Nam" />
    <variable id="IdeThm" type="INTEGER" name="IdeThm" />
    <variable id="ScrIni" type="STRING" name="ScrIni" />
    <variable id="Res" type="STRING" name="Res" />
    <variable id="Act" type="INTEGER" name="Act" />
  </insert>
</target>

Update example​

<target name="ProUpd">
  <update audit="HISAwePro">
    <table id="AwePro" />
    <field id="IdePro" variable="IdePro" />
    <field id="Acr" variable="Acr" />
    <field id="Nam" variable="Nam" />
    <field id="IdeThm" variable="IdeThm" />
    <field id="ScrIni" variable="ScrIni" />
    <field id="Res" variable="Res" />
    <field id="Act" variable="Act" />
    <where>
      <and>
        <filter left-field="IdePro" condition="eq" right-variable="IdePro" />
      </and>
    </where>
    <variable id="IdePro" type="INTEGER" name="IdePro" />
    <variable id="Acr" type="STRINGN" name="Acr" />
    <variable id="Nam" type="STRINGN" name="Nam" />
    <variable id="IdeThm" type="INTEGER" name="IdeThm" />
    <variable id="ScrIni" type="STRING" name="ScrIni" />
    <variable id="Res" type="STRING" name="Res" />
    <variable id="Act" type="INTEGER" name="Act" />
  </update>
</target>

Delete example​

<target name="ProDel">
  <delete multiple="true" audit="HISAweModPro">
    <table id="AweModPro" />
    <field id="IdePro" variable="IdePro" audit="true" />
    <where>
      <and>
        <filter left-field="IdePro" condition="eq" right-variable="IdePro" />
      </and>
    </where>
    <variable id="IdePro" type="INTEGER" name="IdePro" />
  </delete>
  <commit/>
  <delete multiple="true" audit="HISAweScrRes">
    <table id="AweScrRes" />
    <field id="IdePro" variable="IdePro" audit="true" />
    <where>
      <and>
        <filter left-field="IdePro" condition="eq" right-variable="IdePro" />
      </and>
    </where>
    <variable id="IdePro" type="INTEGER" name="IdePro" />
  </delete>
</target>

This example also shows two important points:

  • multiple="true" means the variable can represent a list of values.
  • <commit/> lets you separate write stages explicitly when needed.

Multiple grid operations​

When an editable grid can mix inserts, updates, and deletes in one batch, use a multiple maintain target.

<target name="ScrAccUpd">
  <multiple audit="HISAweScrRes" grid="GrdScrAccLst">
    <table id="AweScrRes" />
    <field id="IdeAweScrRes" variable="IdeAweScrRes" sequence="ScrResKey" key="true" />
    <field id="IdePro" variable="IdePro" />
    <field id="IdeOpe" variable="IdeOpe" />
    <field id="IdeMod" variable="IdeMod" />
    <field id="Opt" variable="Opt" />
    <field id="AccMod" variable="AccMod" />
    <field id="Act" variable="Act" />
    <variable id="IdeAweScrRes" type="INTEGER" name="IdeAweScrRes" />
    <variable id="IdeOpe" type="INTEGER" name="IdeOpe"/>
    <variable id="IdePro" type="INTEGER" name="IdePro"/>
    <variable id="IdeMod" type="INTEGER" name="IdeMod"/>
    <variable id="Opt" type="STRING" name="Opt" />
    <variable id="AccMod" type="STRING" name="AccMod" />
    <variable id="Act" type="INTEGER" name="Act" />
  </multiple>
</target>

This pattern relies on the grid context to tell AWE which row operation to execute.

Advanced topics​

The sections below are useful, but they are not the first stop for most screens.

Envío de correo electrónico​

Email definitions live in Email.xml and are often triggered from a maintain target.

<email id="TransfersSNCEEmaRep">
  <from value="FromValue" label="FromValue" />
  <to label="RepEmaDst" value="RepEmaDst" />
  <subject label="RepTit" value="RepTit" />
  <body label="RepMsg" type="html" value="RepMsg"/>
  <body label="RepMsg" type="text" value="RepMsg"/>
  <variable type="STRING" id="FromValue" property="sch.report.email"/>
  <variable type="STRING" id="RepMsg" name="RepMsg"/>
  <variable type="STRING" id="RepTit" name="RepTit"/>
</email>
<target name="SndRep">
  <send-email id="SndRep" />
</target>

Conexión con colas de mensajes​

Queue integrations are defined in Queues.xml and are typically used when AWE must exchange data with external messaging infrastructure.

<queues xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://aweframework.gitlab.io/awe/docs/schemas/queues.xsd">
  <queue id="TstGrdQue">
    <request-message destination="AweReq" type="MAP" selector="grid">
    </request-message>
    <response-message destination="AweRes" type="MAP">
      <message-parameter id="OutFld1" type="STRING" name="MapKey1" list="true" />
      <message-parameter id="OutFld2" type="STRING" name="MapKey2" list="true" />
      <message-parameter id="OutFld3" type="STRING" name="MapKey3" list="true" />
      <message-parameter id="OutFld4" type="STRING" name="MapKey4" list="true" />
    </response-message>
  </queue>
</queues>

Service-backed retrieval or writes​

Services can back queries or maintains when database-only XML is not enough.

From a query:

<query id="GetFechasCancelacionesSup" service="GetFilteredDates">
  <field id="label" alias="label" transform="DATE" function="TRUNCDATE" />
  <field id="value" alias="value" transform="DATE" function="TRUNCDATE" />
  <variable id="Dias" type="INTEGER" name="Dias" value="10" />
</query>

From a maintain:

<target name="checkYearHolidays">
  <serve service="checkYearHolidays"/>
</target>

If you need to implement the service itself, continue with awe-107.

What to do next​

  • Use awe-107 when data retrieval or persistence must call Java logic.
  • Use awe-106 when screens need to react dynamically to values or server results.
  • Use the API reference for full descriptor coverage once the basic data path is already clear.