Implement External Entities

• An external entity modelled in Solution Designer acts as a pointer / reference to an entity that may reside in another system

• Using a generated external entity service we can implement the logic for:

  1. create, creates the external entity pointer / reference

  2. load, loads the full details of that external system Entity and map it to one of modelled Domain Entities

  3. validate, validates that the referenced Entity still exists in the external system and optionally update the External Entity data

• For each external entity there will be an abstract class External Entity Service Base generated in the SDK

• The External Entity Service Base provides access to the repository and entity builder

• The External Entity Service Base contains three abstract methods create, load, and validate

• These three methods needs to be implemented in the generated implementation file for the External Entity

The create function is used to construct a local instance of the External Entity and initialize the associated properties with certain pre-specified values that are provided as input parameters.

• create method will take modelled constructor properties as a parameters.

• constructor properties acts as identifiers to be able to retrieve full data external entity that might reside in an external system.

• create method will return modelled External Entity as a return type.

The load function implements logic to call external system and loads the full external entity data.

• load method will take modelled External Entity as a parameter.

• Depending on the logic, load can connect to external system, and retrieve full data of Entity, that is referenced by External Entity, then map it to one of Domain Entity.

• load method will return an instance of an Entity.

The validate method is used to validate the stored entity information by loading the data from the external service. It is recommended to also implement the logic of updating the external entity within the validate method.

• validate method will take modelled External Entity as first parameter.

• validate method update flag helps to determine whether the External Entity should be updated with the result from the external service or not

Example of Balance External Entity service implementation file.

    //... imports

    @Service
    public class BalanceService extends BalanceServiceBase {

      private static Logger log = LoggerFactory.getLogger(BalanceService.class);

      public BalanceService(DomainEntityBuilder entityBuilder, Repository repo){
        super(entityBuilder,repo);
      }

      @Override
      public Balance create(String customerId) {

        log.info("BalanceService.create()");
        
        // Make external calls using the customerId , to get the data of External Entity
        RestTemplate restTemplate = new RestTemplate();
        JsonObject responseObject = restTemplate
        .getForObject("https://some-url/balance/"+ customerId, JsonObject.class);

        Balance balance = this.entityBuilder.getCc().getBalance().build();
        balance.setCustomerId(customerId);

        // Extract properties from responseObject and set it to balance entity

        return balance;
      }

      /**
      * Load external Entity and return as an Entity
      *
      * @param externalEntity instance of Balance
      * @return class that extends base type Entity
      */
      @Override
      public Entity load(Balance externalEntity) {

        log.info("BalanceService.load()");

        return null;
      }

      /**
      * validate the existence of the external entity in the external system.
      *
      * @param externalEntity instance of Balance.
      * @param update          flag to indicate whether should an updated
      *                        Balance instance be created and
      *                        returned or not.
      * @return Optional Balance instance to indicate whether
      *         external entity still exists in external system
      */
      @Override
      public Optional<Balance> validate(Balance externalEntity, boolean update) {

        log.info("BalanceService.validate()");

        // Make external calls to validate if external entity still exists
        RestTemplate restTemplate = new RestTemplate();
        JsonObject responseObject = restTemplate
        .getForObject("https://some-url/has-balance/"+ externalEntity.getCustomerId(), JsonObject.class);

        // Need to handle cases:
        // 1. external entity no longer exists
        // 2. If update is set to true, should update the @param *externalEntity* data and return it.

        return Optional.of(externalEntity);
      }
    }