Implement External Entities

The constructor 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 properties.

//**
* constructor method of external entity reference
*/
public create(): void {
   const log = this.util.log;
   log.debug('Constructor.execute()');

   // Initialize the value of the associated properties to the input value store in the construc-tor parameter and to a predefined value
   this.instance.associatedProperty1 = this.input.constructorProperty1;
   this.instance.associatedProperty1 = value1;
}

The loader is used to load the external instance. This is normally done by calling a REST service of the integration namespace.

When calling a service (REST or normal), it is important to check whether the output exists, and it is not void. Due to type safety, if the check does not occur, then it is not possible to access the properties of the returned object. This is to prevent accessing properties that may not exist. This check is necessary for calling functions that are built to return two different types such as services that return either void or their output entity.

/**
* load method of external entity reference - loads external entity from external system
*/
public async load(): Promise<void> {
   const log = this.util.log;
   log.debug('Load.execute()');
   
  // Initialize the input of the REST integration service
   const input = this.factory.entity.cust. ServiceIdentifier_Input();

  // Initialize the input properties to their values
   input.property1 = “value1”; // or this.instance.(…)

  // Call the REST service and pass as input the the input entity created above
   const serviceOutput = await this.services.intnsacrnm.ServiceIdentifier (input);

   // Check if the output of the service is not void
   if(serviceOutput) {
     
     // Initialize the output of the loader of the external entity
     this.output = this.factory.nsacrnm.ExternalEntityIdentifier_Output()

     // Set the values of the output properties of the output
     this.output.property1 = serviceOutput.property1;
     this.output.property2 = serviceOutput.property2; 
   }
}

The validator gives information regarding the existence of a specific instance of an external entity. It usually returns true if the external instance exists and false if it does not exist. The validator can also be used for updating the local instance of an external entity if the update flag is set to true.

/**
* validate method of external entity reference - checks if external entity still exists in external system
* @param update indicates whether local properties should be updated after validating entity on external system
* @returns boolean indicating whether external entity still exists in external system
*/
public async validate(update: boolean): Promise<boolean> {
    const log = this.util.log;
    log.debug('Validate.execute()');

    // trigger load function of external entity in order to validate whether the entity still exists
    const existence = await this.instance.load();

    // If it exists return true. Otherwise, return false.
    if(existence) {
      return true;
    } else {
      return false;
    }
}

To make use of the external entities, the SDK provides a Factory for them. The factory offers methods to create new external entity objects, grouped by the namespaces in which the entities are defined. When using those, the constructor method of the external entity is called, which returns the local instance of the external entity from which it is possible to access the associated properties as well as call the load and validate methods.

Please see the example below:

// Initialize the input to the external entity constructor
const input = this.factory.entity.ExternalEntityIdentifier_Input();

// Create external entity reference
const extEntity = await this.factory.external.nsacrnm.ExternalEntityIdentifier(input);

// Access the associated properties 
extEntity.assProp1;

// Load external entity - no input needed
const extEntityInstance = await extEntity.load();

// Now, one can access the properties and their values (read-only) of the specific instance
extEntityInstance.property1;
extEntityInstance.property2;

// Validate the existence specific instance - this will return true or false
const valResult = await extEntity.validate();