Entity Definition

Entity Definition is a Java class which represents the structure of the Entity Class. It is a Java class (.java) and it is located into ENTITIES folder in a Kokos DSL library.

The syntax is similar to Java JPA and is enriched with annotations.

Base Definition

The base definition includes:

• Base informations: (Class type, Class description)
• Attributes
• Actions

As follow a definion of Employees (CNCOL):

import com.smeup.kokos.entities.annotations.*;

@SmeupObj(type = "CNCOL", description = "Employee")
public class CNCOL {

    @Id
    @SmeupOav(id = "I/01", type = "CNCOL", description = "Code")
    private String code;

    @Description
    @SmeupOav(id = "I/02", type = "", description = "Name")
    private String description;

    @SmeupOav(id = "I/03", type = "", description = "Address")
    private String address;

    @SmeupOav(id = "I/04", type = "", description = "City")
    private String city;

    @SmeupOav(id = "I/05", type = "TAV§P", description = "Province")
    private String province;

    @SmeupOav(id = "I/15", type = "TAV§N", description = "State")
    private String state;

    @Action(id = "DET", description = "Open Detail", exec = "F(EXD;*SCO;) 1(CN;COL;[K1]) G(NFIR)", icon = "VO;COD_SOS;000128")
    private void details() {
    }

    @Action(id = "EDT", description = "Edit Detail", exec = "F(EXD;*SCO;) 1(CN;COL;[K1]) 2(MB;SCP_SCH;OG_ISTA) 4(;;EDT) G(NFIR)", icon = "VO;COD_VER;000112")
    private void edit() {
    }
    
}

The base definition is a simple Java class composed by attributes (i.e. private String code;) and actions (i.e. private void details() {}). To properly define the base informations, attributes and actions you can use the following Java annotations:

@SmeupObj: Define the base informations

Arguments:

• type (string): the entity type
• description (string): the entity description

---

@SmeupOav: Define and attribute (OAV)

Arguments:

• id (string): the id of OAV (es. I/01, G/02...)
• type (string): the OAV type. Can be another entity
• description (string): the attribute description

---

@Action: Define an action

Arguments:

• id (string): the action id
• description (string): the action description
• exec (string): the action function (FUN)
• icon (string): the action icon

Each OAV have a real value based on primitive types. You can define it using Java Wrapper classes:

• INTEGER: java.lang.Integer

• DECIMAL: java.lang.Double

• LONG: java.lang.Long

• STRING: java.lang.Stirng

• BOOLEAN: java.lang.Boolean

• DATE: java.lang.Date

• MONGO OBJECT ID: org.bson.types.ObjectId

• ARRAY: java.util.List (es. List<String>, List<Integer>...)

Data Source Definition

The Data Source Definition is used to identify the locations of the entity's data. Data can be located in:

• Relational Database (MySql, SQLServer, DB2...)
• Document Oriented Database (MongoDB)
• WebService APIs
• Custom Service

How to configure data sources ?

See offical docs to learn how configure a data source.

Relational Database

To include Relational Database you can use @Table annotation and setup the table or the query. Then you can set @Column annotation for each oav you can map as a Relational Database column.

As follow a definion of Employees (CNCOL) defined in BRENTI0F table:

import com.smeup.kokos.entities.annotations.*;

@Table(dataSourceId = "default_mysql_playground", query = "SELECT * FROM BRENTI0F WHERE \"E§TRAG\"='COL'")

@SmeupObj(type = "CNCOL", description = "Employee")
public class CNCOL {

    @Id
    @Column(table = "BRENTI0F", columnName = "E§CRAG")
    @SmeupOav(id = "I/02", type = "CNCOL", description = "Code")
    private String code;

    @Description
    @Column(table = "BRENTI0F", columnName = "E§RAGS")
    @SmeupOav(id = "I/01", type = "", description = "Name")
    private String description;

    @Column(table = "BRENTI0F", columnName = "E§INDI")
    @SmeupOav(id = "I/03", type = "", description = "Address")
    private String address;

    @Column(table = "BRENTI0F", columnName = "E§LOCA")
    @SmeupOav(id = "I/04", type = "", description = "City")
    private String city;

    @Column(table = "BRENTI0F", columnName = "E§PROV")
    @SmeupOav(id = "I/05", type = "TAV§P", description = "Province")
    private String province;

    @Column(table = "BRENTI0F", columnName = "E§CNAZ")
    @SmeupOav(id = "I/15", type = "TAV§N", description = "State")
    private String state;

    @Column(table = "BRENTI0F", columnName = "E§AZIE")
    @SmeupOav(id = "I/B2", type = "", description = "Company Code")
    private String companyCode;
    
}

@Table: Define a Relational Datasource

Arguments:

• dataSourceId (string): the id of data source (data_source_definition.yaml)
• table (string): table name
• query (string): SQL query

---

@Column: Map an OAV to a Column field

Arguments:

• table (string): table name
• columnName (string): column name

Document-Oriented Database

To include Document-oriented Database you can use @Collection annotation and setup the table or the query. Then you can set @DocumentField annotation for each oav you can map as a field of the document.

As follow a definion of Task Workers (CF250001) defined in MU250001 MongoDB collection:

import com.smeup.kokos.entities.annotations.*;
import org.bson.types.ObjectId;

@Collection(dataSourceId = "default_mongodb_playground", name = "MU250001", query = "{}")

@SmeupObj(type = "CFMU250001", description = "Task Worker")
public class CFMU250001 {
  
  @Id
  @DocumentField(key = "_id")
  @SmeupOav(id = "I/01", type = "CFMU250001", description = "Id")
  private ObjectId id;

  @Description
  @DocumentField(key = "name")
  @SmeupOav(id = "I/02", type = "", description = "Name")
  private String name;

  @DocumentField(key = "job")
  @SmeupOav(id = "I/03", type = "", description = "Job")
  private String job;
  
}

@Collection: Define a Document-Oriented Datasource

Arguments:

• dataSourceId (string): the id of data source (data_source_definition.yaml)
• name (string): collection name
• query (string): NoSQL query

---

@DocumentField: Map an OAV to a Column field

Arguments:

• key (string): document key

---

We support also dot notation to access to the document fields when the field value is an object, see below example

Document stored in mongo:

{
  "_id": {
    "$oid": "65f42871b2c9bf00df505815"
  },
  "name": "THOMAS SHELBY",
  "address": {
    "country": {
      "iso": "UK",
      "name": "United Kingdom"
    },
    "city": "Birmingham"
  }
}

The entity definition to read and write the document will be defined like this:

@Description
@DocumentField(key = "name")
@SmeupOav(id = "I/02", type = "", description = "Name")
private String name;

@DocumentField(key = "address.country.iso")
@SmeupOav(id = "I/04", type = "", description = "Country (iso)")
private String addressCountryIso;

@DocumentField(key = "address.country.name")
@SmeupOav(id = "I/05", type = "", description = "Country (name)")
private String addressCountryName;

@DocumentField(key = "address.city")
@SmeupOav(id = "I/06", type = "", description = "Address (city)")
private String addressCity;

Custom Service

You can also create a Service to get the Entity data. The service must expose the following methods:

Action	Method	FUN
findById	FND.BID	F(EXB;XXX;FND.BID) 1([T];[P];[K])
findMany	FND.MNY	F(EXB;XXX;FND.MNY) 1(OG;;[T][P]) INPUT(IDS(xxx;yyy;zzz))
find	FND.ALL	F(EXB;XXX;FND.ALL) 1(OG;;[T][P])
insert	INS.NEW	F(EXB;XXX;INS.NEW) 1([T];[P];[K]) INPUT(OAVS(oav_key(oav_value) oav_key(oav_value)...))
update	UPD.BID	F(EXB;XXX;UPD.BID) 1([T];[P];[K]) INPUT(OAVS(oav_key(oav_value) oav_key(oav_value)...))
delete	DEL.BID	F(FBK;XXX;DEL.BID) 1([T];[P];[K])

SDK java allows you to simplify the development of the service extending the abstract class: com.smeup.kokos.sdk.entity.KokosEntityDAOService.

To define the name of the service you can use @Service annotation.

Arguments:

• name (string): the name of the service

As follow a definion of Patient (CNPAZ) with data retrieved from the MU_240_J1 service:

import com.smeup.kokos.entities.annotations.*;

@Service(name = "MU_240_J1")
@SmeupObj(type = "CNPAZ", description = "Patients")
public class CNPAZ {
    @Id
    @SmeupOav(oav = "A/10", type = "CNPAZ", description = "Id")
    private String code;

    @SmeupOav(oav = "A/03", type = "", description = "Name")
    private String name;

    @SmeupOav(oav = "A/02", type = "", description = "Active")
    private String active;

    @SmeupOav(oav = "A/05", type = "", description = "City")
    private String city;

    @SmeupOav(oav = "A/06", type = "", description = "State")
    private String state;

    @SmeupOav(oav = "A/09", type = "", description = "Gender")
    private String gender;
}

Custom Program

In a similar way to what is done with services, you can also create a Program to get the Entity data.

SDK java allows you to simplify the development of the program extending the abstract class: com.smeup.kokos.entities.dao.program.AbstractProgramEntityDAO.

To define the name of the program you can use @Program annotation.

Arguments:

• name (string): the name of the Program

As follow a definion of /Copy (SACPYAPI) with data retrieved from the CopyEntityDAO Program:

import com.smeup.kokos.entities.annotations.*;

@Program(name = "CopyEntityDAO")

@SmeupObj(type = "SACPY.API", description = "/Copy")
public class SACPYAPI {

	@Id
	@SmeupOav(id = "G/10", type = "SACPY.API", description = "Code")
	private String code;

	@Description
	@SmeupOav(id = "G/12", type = "", description = "Description")
	private String description;

	@SmeupOav(id = "I/30", type = "V2SI/NO", description = "Changed")
	private Boolean changed;

	@SmeupOav(id = "I/31", type = "V2SI/NO", description = "Doped")
	private Boolean doped;

}

Multiple Data Source Definition

You can define multiple data source for the same entity. The syntax is the same as previous but the commons attributes can mapped with both annotations. As follow an example using MySQL and MongoDB at same time.

import com.smeup.kokos.entities.annotations.*;

@Table(dataSourceId = "default_mysql_playground", query = "SELECT * FROM BRENTI0F WHERE \"E§TRAG\"='CLI'")
@Collection(dataSourceId = "default_mongodb_playground", name = "CNCLI", query = "{}")

@SmeupObj(type = "CNCLI", description = "Customer")
public class CNCLI {

    @Id
    @Column(table = "BRENTI0F", columnName = "E§CRAG")
    @DocumentField(key = "code")
    @SmeupOav(id = "I/02", type = "CNCLI", description = "Code")
    private String code;

    @Column(table = "BRENTI0F", columnName = "E§TRAG")
    @SmeupOav(id = "I/53", type = "", description = "Type")
    private String type;

    @Description
    @Column(table = "BRENTI0F", columnName = "E§RAGS")
    @SmeupOav(id = "I/01", type = "", description = "Name")
    private String description;

    @Column(table = "BRENTI0F", columnName = "E§INDI")
    @SmeupOav(id = "I/03", type = "", description = "Address")
    private String address;

    @Column(table = "BRENTI0F", columnName = "E§LOCA")
    @SmeupOav(id = "I/04", type = "", description = "City")
    private String city;

    @Column(table = "BRENTI0F", columnName = "E§PROV")
    @SmeupOav(id = "I/05", type = "TAV§P", description = "Province")
    private String province;

    @Column(table = "BRENTI0F", columnName = "E§CNAZ")
    @SmeupOav(id = "I/15", type = "TAV§N", description = "State")
    private String state;

    @DocumentField(key = "vat")
    @SmeupOav(id = "I/08", type = "", description = "VAT")
    private String vat;

    @DocumentField(key = "taxIdentificationNumber")
    @SmeupOav(id = "I/09", type = "", description = "Tax Identification Number")
    private String taxIdentificationNumber;

    @DocumentField(key = "commission")
    @SmeupOav(id = "I/24", type = "NRP", description = "Commission")
    private Double commission;
  
}

NB

Reading data from data sources involves more expensive operations, which is why it should not be routine

Custom Filter Function

For greater flexibility, it is also possible to specify the appropriate database function for a specific field using @Filter annotation. For example, if you are using MySQL and you want the field to be uppercase each time a filter is applied, you can work as follows:

  @Column(table = "DUMMY", columnName = "COUNTRY")
	@Filter(fieldFunction = "[DATABASE_FUNCTION]", fieldValueFunction = "[DATABASE_FUNCTION]")
	@SmeupOav(id = "I/04", type = "TAV§S", description = "Country")
	private String country;

Arguments:

• fieldFunction (string): specific data source function for field (es. MySQL UPPERCASE...)
• fieldValueFunction (string): specific data source function for field value (es. MySQL UPPERCASE...)

es. To create a case insensitive filter in MySQL:

@Column(table = "DUMMY", columnName = "COUNTRY")
@Filter(fieldFunction = "UPPERCASE(%s)", fieldValueFunction = "UPPERCASE(%s)")
@SmeupOav(id = "I/04", type = "TAV§S", description = "Country")
private String country;

I set UPPERCASE for each element: fieldFunction and fieldValueFunction. The result query always matches.

Entities External Definition

To improve flexibility on entity definition managing, you can add an annotation to get and set the definition on mongodb.

You can see below how it works:

@ExternalEntityDefinition(dataSourceId = "default_mongodb")

@Program(name = "NumberEntityDAO")

@SmeupObj(type = "NR", description = "Number")
public class NR {

	@Id
	@SmeupOav(id = "G/12", type = "NR", description = "Code")
	private String code;

	@Description
	@SmeupOav(id = "G/40", type = "", description = "Description")
	private String description;

}

@ExternalEntityDefinition: Enable the managing of the entity on mongodb

Arguments:

• dataSourceId: Defines the data source id of the mongodb instance and the database name, where the collection which will contain the entity definition will be stored in json format, the collection name is entities

The managing will require use of the service MU_173_02. Go ahead to undestand how it works.