The following document tries to introduce the reader to the Object instance. After reading this article, the reader will know what is an Object instance, how to create and configure it, and which functionalities it implements.

1 Introduction

Every view on WebApp application (Reports, Transactional forms, Rest APIs, etc.) is an instance of this Object entity. This implementation gives a centralized configuration for views, such us the tree menu configuration and views functional grouping.

Furthermore, when defining references to an Object through the application, such as links, automated executions, etc. those reference point to an unique entity, the Object Instance, whatever the type of Object it is.

Finally, most of the Objects requires a process of query in order to narrow the data to be displayed on the view. This is what we call QBE (Query By Example); which consists on a set of parameters that provide the user an user friendly form with a set of input fields for specifying what data wants to manage. So, the Object instance provides the entities: Query fields, Query variables and Meta queries to implement the mentioned QBE.

To sum up, the Object instance is intended for providing:

  • Simplified application menu configuration.
  • Simplified Object references within application.
  • Centralized description and localization.
  • Centralized query.

2 Definition

Review pending

To define an object instance, it is necessary to access the definiiton form wic_obj_base in the application dictionary.

Menu path:
[SOAPException: faultCode=SOAP-ENV:Protocol; msg=Unsupported response content type "text/html;charset=utf-8", must be: "text/xml". Response was: Error ] at org.apache.soap.rpc.Call.getEnvelopeString(Call.java:241) at org.apache.soap.rpc.Call.invoke(Call.java:307) at org.apache.soap.api.client.SOAPHTTPClient.__getResponse(SOAPHTTPClient.java:481) at org.apache.soap.api.client.SOAPHTTPClient.__doSOAPCall(SOAPHTTPClient.java:418) at org.apache.soap.api.client.SOAPHTTPClient.doSOAPCall(SOAPHTTPClient.java:346) at deister.axional.server.soap.client.SOAPClient.__doSOAPCall(SOAPClient.java:715) at deister.axional.server.soap.client.SOAPClient.doSOAPCall(SOAPClient.java:570) at deister.axional.docs.xsl.CMSSOAPClient.__doSOAPCall(CMSSOAPClient.java:98) at deister.axional.docs.xsl.CMSSOAPClient.getDictionaryObjectData(CMSSOAPClient.java:197) at java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke0(Native Method) at java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62) at java.base/jdk.internal.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43) at java.base/java.lang.reflect.Method.invoke(Method.java:566) at org.apache.xalan.extensions.ExtensionHandlerJavaPackage.callFunction(ExtensionHandlerJavaPackage.java:343) at org.apache.xalan.extensions.ExtensionHandlerJavaPackage.callFunction(ExtensionHandlerJavaPackage.java:440) at org.apache.xalan.extensions.ExtensionsTable.extFunction(ExtensionsTable.java:222) at org.apache.xalan.transformer.TransformerImpl.extFunction(TransformerImpl.java:475) at org.apache.xpath.functions.FuncExtFunction.execute(FuncExtFunction.java:208) at org.apache.xpath.objects.XRTreeFragSelectWrapper.execute(XRTreeFragSelectWrapper.java:69) at org.apache.xpath.XPath.execute(XPath.java:337) at org.apache.xalan.templates.ElemVariable.getValue(ElemVariable.java:280) at org.apache.xalan.templates.ElemVariable.execute(ElemVariable.java:248) at org.apache.xalan.transformer.TransformerImpl.executeChildTemplates(TransformerImpl.java:2402) at org.apache.xalan.templates.ElemTemplate.execute(ElemTemplate.java:394) at org.apache.xalan.templates.ElemCallTemplate.execute(ElemCallTemplate.java:248) at org.apache.xalan.transformer.TransformerImpl.executeChildTemplates(TransformerImpl.java:2402) at org.apache.xalan.templates.ElemChoose.execute(ElemChoose.java:141) at org.apache.xalan.templates.ElemApplyTemplates.transformSelectedNodes(ElemApplyTemplates.java:395) at org.apache.xalan.templates.ElemApplyTemplates.execute(ElemApplyTemplates.java:178) at org.apache.xalan.transformer.TransformerImpl.executeChildTemplates(TransformerImpl.java:2402) at org.apache.xalan.templates.ElemChoose.execute(ElemChoose.java:128) at org.apache.xalan.templates.ElemApplyTemplates.transformSelectedNodes(ElemApplyTemplates.java:395) at org.apache.xalan.templates.ElemApplyTemplates.execute(ElemApplyTemplates.java:178) at org.apache.xalan.transformer.TransformerImpl.executeChildTemplates(TransformerImpl.java:2402) at org.apache.xalan.templates.ElemLiteralResult.execute(ElemLiteralResult.java:1376) at org.apache.xalan.transformer.TransformerImpl.executeChildTemplates(TransformerImpl.java:2402) at org.apache.xalan.templates.ElemLiteralResult.execute(ElemLiteralResult.java:1376) at org.apache.xalan.transformer.TransformerImpl.executeChildTemplates(TransformerImpl.java:2402) at org.apache.xalan.templates.ElemLiteralResult.execute(ElemLiteralResult.java:1376) at org.apache.xalan.transformer.TransformerImpl.executeChildTemplates(TransformerImpl.java:2402) at org.apache.xalan.templates.ElemLiteralResult.execute(ElemLiteralResult.java:1376) at org.apache.xalan.transformer.TransformerImpl.executeChildTemplates(TransformerImpl.java:2402) at org.apache.xalan.templates.ElemLiteralResult.execute(ElemLiteralResult.java:1376) at org.apache.xalan.transformer.TransformerImpl.executeChildTemplates(TransformerImpl.java:2402) at org.apache.xalan.templates.ElemLiteralResult.execute(ElemLiteralResult.java:1376) at org.apache.xalan.templates.ElemApplyTemplates.transformSelectedNodes(ElemApplyTemplates.java:395) at org.apache.xalan.templates.ElemApplyTemplates.execute(ElemApplyTemplates.java:178) at org.apache.xalan.transformer.TransformerImpl.executeChildTemplates(TransformerImpl.java:2402) at org.apache.xalan.transformer.TransformerImpl.applyTemplateToNode(TransformerImpl.java:2272) at org.apache.xalan.transformer.TransformerImpl.transformNode(TransformerImpl.java:1358) at org.apache.xalan.transformer.TransformerImpl.transform(TransformerImpl.java:711) at org.apache.xalan.transformer.TransformerImpl.transform(TransformerImpl.java:1275) at org.apache.xalan.transformer.TransformerImpl.transform(TransformerImpl.java:1253) at deister.axional.server.lang.xsl.XSLProcessor.__execute(XSLProcessor.java:862) at deister.axional.server.lang.xsl.XSLProcessor$4.call(XSLProcessor.java:699) at deister.axional.server.lang.xsl.XSLProcessor$4.call(XSLProcessor.java:691) at java.base/java.util.concurrent.FutureTask.run(FutureTask.java:264) at java.base/java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1128) at java.base/java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:628) at java.base/java.lang.Thread.run(Thread.java:834)

The definition form is divided in parts, all common to all object types except for the Report tab, which is unique for Report instances.

  1. Report tab: only for report instances
  2. Identification:
    • Object code*: it must be the unique identifier. Use conventional syntax, with lowercase letters and underscore between separate words. Preferably, give a meaningful name to the object.
    • Tag name: it corresponds to the name that will be displayed in the object's tab. Capitalize the first letter of the tag name.
    • Title*: it is the text that appears in the object header. Use capital letters.
  3. Additional info:
    • Group*: this field corresponds to the functional groups of objects and panels and serves two major functions. On the one hand, to assign role permissions through the wic_conf. On the other, to control some aspects related to the appearance and color of the object.
    • Type*: select between Report (0), Transactional (1) of REST Application (2). Report (0) set by default.
    • Locked: if the locked box is disabled, then the object can be selected and executed. Enable it if the object is being design or under revision.
  4. Input tabs:
    • Input query: defines the fields on the query form.
    • Input variables: defines complex query fields.
    • Input meta query: defines quick access query fields.
  5. Help tabs:
    • Object info: help text description to be reported when user clicks on object instance help icon. Use PARSEXML format.
    • Snapshot: picture of an object instance example.
    • Language: help text description translated into other languages.
  6. Control data: standard information about object instance.
    • ID: instance identification number.
    • Created by: user who created it.
    • Date created: date of registering.
    • Modified by: user who modified it.
    • Date updated: date of last update.

3 Input query fields

Review pending

When we talk about databases, a query is a request for data stored in that DB. Queries are a way of searching for and compiling data from one or more tables.

The QBE (Query By Example) provides a simple interface for a user to enter queries. Instead of writing an entire SQL command, the user can just fill in blanks or select items to define the desired query. Each query field represents a field in a table that you want to consult. Usually, entries are only made in query fields for which you want to specify search criteria.

The query fields must be defined through the object instance form:

Query fields are only applicable to the following object types:

  • Reports
  • Transactional

The components that define a query field are:

  • Order: the order in which the input fields will appear.
  • Group: allows grouping query fields to be used separatelly in statemement. Use $QRY1, $QRY2, ..., instead of the unique $0. The default value 0 is equivalent to $set. Different groups of input fields can be implemented, for example, so that some selects only affect a subset of fields.
  • Table: table where to consult the query.
  • Column: name of the column you want to provide the user with the possibility of introducing a selection criterion.
  • Query: defines a different field to the column field so that it takes a logical dictionary with an alias, but when applying it to the SQL cond it makes a specific query.
  • Required: determines whether a query field is required, or whether it is displayed on the primary or secondary query screen.
  • Default: allows assigning default values to a query field.

SOFT REFERENCES

The input field inherits the soft reference from table and column definition. Soft Reference implementation is detailed in chapter Advanced features, section Soft References

When the user enters some selection criteria in the input fields of an object, the system will translate it into SQL language, and will add it to the end of the SQL statement built for the query to the database.

When the object consists of a simple SQL statement, that is, a single SELECT statement intervenes, the object will be executed without any problem.

When the object consists of a complex SQL statement, in which several SELECT instructions are involved, or it consists of a GROUP BY clause, then it will have to be indicated, using the AND $ 0 operator, the appropriate place in the SQL statement where we want the system to add the syntax of the selection criteria entered by the user.

Attention

When the SQL statement of an object consists of two SELECT clauses joined by a UNION or UNION ALL clause, it could happen that the tables registered in the input fields of the object were valid for one of them and not for the other, which would lead to the error that the table does not belong to the list of tables indicated in the clause.

This could happen because as the input fields have the name of the table implicit, if any of the tables in those fields were not included in the FROM clause of any of the instructions, this would lead to an SQL error.

When such a case occurs, it is recommended to use and define query variables , for those input fields that are not common and valid for this type of SQL constructs. Query variables do not imply the name of any table; which would allow to skip the error that occurred previously.

It should be noted that in an object you could define input fields and query variables at the same time, for the input of the user's selection criteria. To distinguish them, the system will display them in different colors: the input fields being colored blue and the variables color green or violet depending on their type.

3.1 Order

The input order will be the one corresponding to the order in which the system will present the input fields to the user, when entering the selection criterion.

If the object had query variables associated, the input fields are displayed fisrt, and afterwards the variables are displayed.

3.2 Group

TO DO

This section is incomplete and will be concluded as soon as possible.

3.3 Table and Column

Name of the table and column you want to provide the user with the possibility of introducing a selection criterion.

The column reported here, for the indicated table, should be registered in the wic_jdic_coldata column dictionary on the system.

IMPORTAN

As a column name, the character * would be accepted.
This option avoids having to register all the columns of the mentioned table. This would be equivalent to registering as input fields, of all the columns belonging to the indicated table.

3.4 Default

Query fields allow specifying a default value on by specifying one value on the Default attribute at Query Fields entity (wic_obj_inputqry.qry_defvalue). Although the user can modify this default value before executing the query, its use is recommended in those cases where it is the most common query value.

When defined, the QBE page will initially display the input field with the corresponding value.

3.4.1 Query

3.4.2 Syntax

TO DO

This section is incomplete and will be concluded as soon as possible.

3.5 Required value

Query fields can be marked as required via the Required attribute at Query Fields entity (wic_obj_inputqry.qry_isrequired).

This field can take three possible values:

  • Important: the field will appear on the main query screen (in constrast with unusual). If present, click on See more field in order to see secondary screen.
  • Unusual: the field only appears if user displays the secondary screen of the query.

  • Required: the query is not executed until this field is filled

    Setting a query field as required has two affectations in Axional Studio application:

    • Invalidating the form at QBE page until all required query fields are filled. So, the query cannot be executed from QBE page if there are missing values on required query fields.
    • All URLs executing an object with missing required query fields will be redirected to the QBE Page. That is, by no means an object will be executed without specifying a value for a required query field.

3.6 Use in statement

The final goal of QBE page is to generate an SQL clause that will be used in a server side statement as a filter condition to limit the number of rows to be displayed in a view. The following section explains the process of conversion from the introduced QBE params into the mentioned SQL clause.

3.6.1 QBE to SQL conversion

The tables below contains the translation between QBE expressions into the corresponding SQL clause.

Common clauses
Type QBE Param QBE Value SQL clause
Equal Firts Name John
Copy
user.first_name = 'John'
Not equal Firts Name !=John
Copy
user.first_name != 'John'
Is in List Firts Name John|Mary
Copy
user.first_name IN ('John', 'Mary')
Not is in List Firts Name !John|Mary
Copy
user.first_name NOT IN ('John', 'Mary')
Empty Firts Name =
Copy
user.first_name IS NULL
Not Empty Firts Name !=
Copy
user.first_name IS NOT NULL
Character fields
Type QBE Param QBE Value SQL clause
Starts with Firts Name J%
Copy
user.first_name LIKE 'J%'
Not starts with Firts Name !J%
Copy
user.first_name NOT LIKE 'J%'
Ends with Firts Name %J
Copy
user.first_name LIKE '%J'
Not ends with Firts Name !J%
Copy
user.first_name NOT LIKE '%J'
Contains Firts Name %o%
Copy
user.first_name LIKE '%o%'
Not contains Firts Name !%o%
Copy
user.first_name NOT LIKE '%o%'
Numbers and date fields
Type QBE Param QBE Value SQL clause
Greater than Birth Date >21-05-2019
Copy
user.birth_date > MDY(5, 21, 2019)
Greater or equal then Birth Date >=21-05-2019
Copy
user.birth_date >= MDY(5, 21, 2019)
Lower than Birth Date <21-05-2019
Copy
user.birth_date < MDY(5, 21, 2019)
Lower or equal than Birth Date <=21-05-2019
Copy
user.birth_date <= MDY(5, 21, 2019)
Between Birth Date 01-01-2019:31-12-2019
Copy
user.birth_date BETWEEN MDY(1, 1, 2019) AND MDY(12, 31, 2019)
Not between Birth Date !01-01-2019:31-12-2019
Copy
user.birth_date NOT BETWEEN MDY(1, 1, 2019) AND MDY(12, 31, 2019)

Multiple fields

In case of specifying more than one QBE param they are applied to narrow the filter, so they are joined by the AND operator. For example, applying the QBE params:

  • Firt Name: John
  • Last Name: Smith

The resulting SQL clause is:

Copy
user.first_name = 'John' AND user.last_name = 'Smith'

Dates handling

Notice that dates are introduced in the user format and time zone, and they are translated into the database format and time zone when applied.

Basic Text Search (BTS)

TO DO

This section is incomplete and will be concluded as soon as possible.

3.6.2 QBE statement application in SQL

By default, the SQL clause generated by the QBE is automatically applied to the main SQL statement of the object instance. For example, in case of having the following statement:

Copy
<select>
    <columns>*</columns>
    <from table='customers'/>
</select>

And receiving a QBE clause where the query field customers.cust_id is equal to 2, then the executing statement will be:

Copy
SELECT * 
  FROM customers
 WHERE customers.cust_id = 2;

It works fine with single SQL fragments, which are the most common, but in cases of having more complex statements, with multiple fragments or script execution, it could be necessary to specify where to put the QBE clause. For example, when having the following statement:

Copy
<select intotemp='@tmp_customer'>
    <columns>*</columns>
    <from table='customers'/>
</select>

<select>
    <columns>*</columns>
    <from table='@tmp_customer'/>
</select>

And receiving a QBE clause where the query field customers.cust_id is equal to 2, then the executing statement will be:

TO DO

Explain what happen with the where clause when exists more than one fragment and it is not specify where to put the where clause.

So in that case when can specify where to put the QBE clause with the expression $[grpname], where group name is the code defined. By default, all Query fields has the same group name, with the code 0.

Copy
<select intotemp='@tmp_customer'>
    <columns>*</columns>
    <from table='customers'/>
    <where>
        $0
    </where>
</select>

<select>
    <columns>*</columns>
    <from table='@tmp_customer'/>
</select>
Copy
SELECT * 
  FROM customers
 WHERE customers.cust_id = 2
 INTO TEMP tmp_customer_001;
SELECT * 
  FROM tmp_customer_001;

TO DO

This section is incomplete and will be concluded as soon as possible.

Use of variables

TO DO

This section is incomplete and will be concluded as soon as possible.

3.6.3 Specific SQL clause

TO DO

This section is incomplete and will be concluded as soon as possible.

This functionallity allows having specific attributes on an QBE field and keep SQL statement simple.

3.7 Dictionary attributes

TO DO

This section is incomplete and will be concluded as soon as possible.

3.8 Select all columns

TO DO

This section is incomplete and will be concluded as soon as possible.

4 Query input variables

Review pending

The variables are another mechanism for data filtering. They should be created when the inputs fields cannot be used due to the query complexity.

The variables allow to define input fields to be used in expressions that conform the SQL sentence of an object. Each variable can define their own type and its way of being incorporated to the SQL sentence during the construction phase.

Provisional picture

Query variables are only applicable to the following object types:

  • Reports

The variable input form has the following options:

  • Order: order in which the system presents the input variables to the user.
  • Group: the group name corresponds to the variable name, which will be use in the statement. Sintax: $VARNAME (alphanumerical characters).
  • Table: table name where to perform the query.
  • Column: column name where to perform the query.
  • Query: only for construct type.

    TO DO

    This section is incomplete and will be concluded as soon as possible.
  • Type: select one among the existing options.

4.1 Creteria to create input variables

There are two main causes that force you to create input variables:

  • Selection criteria . As we mentioned when explaining the registration of input fields, there are occasions when in order to make selections by certain fields, it is not possible through that registration.
    The reason is because the name of the table in an input field is implicit in the field in the SQL syntax that the system constructs when querying the database. As the SQL statement of the object consists of several FROM clauses, for some it will be fine and for others it will lead to errors because the table does not belong to the list of tables of that clause.
    In this situation, the most viable and advisable is, for these conflicting fields, to define query variables, since this way we avoid the mentioned errors and the same query can be made as through input fields.
  • Processes . When the SQL statement of an object consists solely of activating a process to which certain parameters reported by the user are passed, the only way to request said parameters from the user is through input or query variables.

NEW FEATURES

NULL VALUES ALLOWED. Now a null value for a variable is allowed as long as the variable is not marked as required.
SOFT REFERENCES. The input field inherits the soft reference from table and column definition. Soft Reference implementation is detailed in chapter Advanced features, section Soft References

4.2 Order

Order in which the system presents the input variables to the user. This command is subject to the input fields that the object has defined. The variables are placed behind the input fields.

4.3 Group

TO DO

This section is incomplete and will be concluded as soon as possible.

4.4 Table and column

Review pending
Table name, if you want the label defined for any column in a table to appear as a description of the request of the variable, having to match the name of the column of this table with the one of the variable. In the case that there is description and a table if it is found, the table is the one that prevails.

4.5 Query

TO DO

This section is incomplete and will be concluded as soon as possible.

4.6 Type of variable

Review pending
  • Char
  • Date
  • DateTime
  • Integer
  • Expression

4.7 Default value

Input variables fields allow specifying a default value.

4.8 Required value

TO DO

This section is incomplete and will be concluded as soon as possible.

Mark this field to make this value required on query.

4.9 Construct

Review pending

Through this indicator, the system is informed if the variable is going to have, in the construction of the SQL statement, a behavior equivalent to a construct field or input field.

Whether or not this indicator is activated will influence the integration of the variable into the syntax of the object's SQL statement.

When a variable is defined as class construct ; that is, this indicator is activated, it will always be included in the syntax of the object's SQL statement as follows:

AND table.field $VARIABLE

regardless of whether the variable is assigned an include, as mentioned in the include type field.

When the system constructs the SQL statement of the query for a variable of this class, depending on the information supplied by the variable, the system will intelligently use the necessary logical operators based on it.

The most usual examples are the following:

  • = . When the variable supplies a single value, for example an fiscal year, the system will create the statement of the form: table.field = 2000 .
  • IN () . If instead of supplying a single fiscal year, you get two values separated by a | , then the sentences would be: table.field IN (1999,2000) .
  • MATCHES . If the value supplied by the variable is linked with a * , in this case the statement would be: table.field MATCHES '* value *' (depending on whether the * has been reported to the left, right of the entered value, or both sides.)
  • BETWEEN . If the values supplied by the variable arrive separated by : , then the statement would be: table.field BETWEEN value1 AND value2 .
  • etc.
  1. In order for a user executing an object to distinguish a construct variable from a normal one, the system presents them in different colors, so that the class construct is will show purple and normal green.
  2. The content of this type of variables, in the context of an xsql-script program, must be defined the unquoted attribute according to the following example: <p_empcode mode='unquoted' />

4.10 Use in statement

TO DO

This section is incomplete and will be concluded as soon as possible.

4.10.1 Normal variables

TO DO

This section is incomplete and will be concluded as soon as possible.

4.10.2 Construct variables

TO DO

This section is incomplete and will be concluded as soon as possible.

QBE to SQL conversion

TO DO

This section is incomplete and will be concluded as soon as possible.

QBE statement application in SQL

TO DO

This section is incomplete and will be concluded as soon as possible.

Specific SQL clause

TO DO

This section is incomplete and will be concluded as soon as possible.

4.11 Dictionary attributes

TO DO

This section is incomplete and will be concluded as soon as possible.

4.11.1 Alternative columns

TO DO

This section is incomplete and will be concluded as soon as possible.

5 Meta query

TO DO

This section is incomplete and will be concluded as soon as possible.

Meta queries are only applicable to the following object types:

  • Reports
  • Transactional