Skip to content

Entity Services APIs

Entity Service is an appropriate API for a System-System Integration. Entity Service APIs (ESA) expose underlying entities (logical units) as OData Services. These services needs to be activated via the API Explorer before they can be used. ( ESA is also known as Data Entity Service - DES).

Usage

Many of the existing Standard Projection APIs are tightly coupled to the Aurena pages they serve. This makes it difficult to reuse these APIs for different requirements. Whilst this gap is fulfilled to a certain extent by the purposely built Integration projections and Premium APIs, the number of such projections are limited and have designed to fulfil specific business scenarios and for integration purposes. The level of composability and discoverability is at minimal level, hence they cannot be reused for new business flows, and hard to identify which to use in different contexts.

Following is the recommended order of consuming different APIs, IFS offers for different integration scenarios?

• Premium APIs – as they are tailor made and fully supported by R&D for specific business scenarios

• (Non-Premium) Integration APIs – intended for integration scenarios

• Standard APIs or DES – If a Standard APIs support a given integration requirement it may be used, otherwise DES is to be considered, especially if composing on lower-level API end points.

• However, DES should NOT be used for external end-user interactive access. For end-user scenarios, refer to above API categories.

Goals and Objectives

  • Expose IFS Entity Models as OData services for performing CRUD operations and State Machine transitions
  • Entity models will get exposed as Rest endpoints without the modelling of a projection.
  • Entity models which are exposed as services will act as stand-alone models for integrations.
  • PL/SQL methods other than CRUD and State Events in *_API package layer, will not be exposed.

Solution

By default all the entities will expose as REST endpoints to outside. This can be regilated using the code generation property "ExposeEntityAsService " at the model level or using the build-property "entityservices" at build time as explain in the next section.

In order to expose an entity as Odata services, all the required metadata and dictionary data deployment code will get generated into the corresponding “APY” file of the “Entity”, as a separate PL block. Methods for supporting CRUD, State Events will be added to the existing API package. Hence method declarations will get generated in the "API" file and the implementations of those methods will get generated in "APY" file of the entity.

NOTE: Since it is not safe to deploy public CRUD methods into API package for all the entities, it is decided to make those methods private by adding double underscore.

PUBLIC DECLARATIONS section and METHODS FOR ENTITYNAMEENTITY section which contains CRUD method declarations will get generated at the end of API file.

Following methods will get generated at the end of the "APY" file.

  1. PRIVATE DECLARATIONS
  2. METADATA PROVIDER METHODS
  3. IMPLEMENTATION METHOD DECLARATIONS
  4. PRIVATE METHODS FOR ENTITYNAMEENTITY which contains CRUD methods implementations.
  5. HELPER METHODS
  6. CONVERSION METHODS sections along with projection metadata and registration section

By default, a projection will be deployed for each entity, if it is not restricted from the codegen property as mention in the next section.

  • Those new projections are of “Integration” type

  • A new metadata called “SOURCE” is added to both metadata and projection registration. For services based on regular projections this will be set to “projection” and for entity services this will be set to “entity” (default value is 'projection')

  • The API class is “StandardEntity”

  • The layer is “Base” for these new projections since it is kind of an internal projection.

The new service endpoint for the entity service API is: host/int/ifsapplications/entity/v1/Entity.svc

Design Decisions

  1. The name of the new projection generated for each entity would be <EntityName>Entity.svc, generated entity service API name by default has “Entity” as a suffix

    Ex: If Account.entity is the entity, AccountEntity.projection would be the projection name

    Therefore a new validation was introduced to avoid munually created standard projections been overwritten by the DES generated projections. Therefore it is not allowed to use "Entity" as a suffix for a standard projection. Validation is available in the Tool as well as in the code generator

  2. A new property in build.properties which can enable /disable in the build (similar to parallel code gen) is introduced to entity services as below.

    To disable entity services: gen.entityservices=false

    To enable entity services: gen.entityservices=true

    By default this feature is enabled from 23R1 and onwards and it can be disabled on demand.

  3. Since DES is enabled by default for all entities, you can use the property "ExposeEntityAsService" to codegenproperties section in the entity to avoid generating the entity as a entity service. If there are entities or areas that are obviously bad to expose as DES, those can be disabled using this property in entity model, so neither the CRUD methods in entity API/APY and middle-tier metadata will get generated nor visible in API explore.

​ ExposeEntityAsService "false";

  1. Solution set files are not considered when generating code for ESA. Hence irrespective of the component is active or not in the solution set file, each entity will get generated as a Entity Service. However Entity Services in inactive components will not be available in API Explorer to consume.

  2. RnD DES behavior of an entity can not control through cust layer. That means with code generation if the entity is from a RnD core component, then eventhough “ExposeEntityAsService = false” is used in the CUST layer of that entity, it is not considered. It will generate the code to expose the entity.

    But in CUST components, the customers can use the “ExposeEntityAsService = false” and control the code generation of their own customization entities. Customers have the authority to decide whether to expose their cust entity as a DES or not.

Exceptions

  1. Considering the current deployment order, it is decided to disable the DES functionality for FNDBAS component. So it is not possible to expose the entities in FNDBAS component.
  2. If DbClientInterface or DbImplementation codegen properties are used in an entity, generation of CRUD methods is controlled accordingly since these codegen properties can restrict the generation of New__ ,Modify__ , Remove__ methods in api.
    • DbClientInterface "update-only" :- if this property is used in the entity, it will expose only the update operation to outside
    • DbClientInterface "read-only” :- if this property is used in the entity, it will expose only the Read option to outside
    • DbImplementation -> “read-only” / “abstract” :- if either of these properties are used in the entity, it will expose only the Read option to outside