General Examples

Input

Set input

The input of a call to a service or a command is set as followed:

// Initialize a variable to the entity type of the input to the service 
const inputToService = this.factory.entity.nsacrnm.ServiceIdentifier_Input();

// Set the values of the input properties
inputToService.property1 = value1;
inputToService.property2 = value2;

// Call the service with the given input
await this.services.nsacrnm.ServiceIdentifier(inputToService);


// Initialize a variable to the entity type of the input to the command
const inputToCommand = this.factory.entity.nsacrnm.CommandIdentifier_Input();

// Set the values of the input properties
inputToCommand.property1 = value1;
inputToCommand.property2 = value2;

// Call a command with the given input

Input as a list

The input of a call to service or command is set as follows:

// create two service input objects 
const input1 = this.factory.entity.nsacrnm.ServiceIdentifier_Input();
const input2 = this.factory.entity.nsacrnm.ServiceIdentifier_Input();
const inputToService = [input1, input2];

// call the service passing the needed array
await this.factory.service.nsacrnm.ServiceIdentifier(inputToService);

// access service input list
const val1 = this.input[0];
const val2 = this.input[1];

Output

Set output

The output of a service is set as follows:

// Initialize a variable to the entity type of the output of the service
const output = this.factory.entity.nsacrnm.ServiceIdentifier_Output();

// Set the values of the output properties
output.property1 = value1;
output.property2 = value2;

Output as a list

The output (as a list) of a service is set as follows:

// create two service output objects 
const output1 = this.factory.entity.nsacrnm.ServiceIdentifier_Output();
const output2 = this.factory.entity.nsacrnm.ServiceIdentifier_Output();

// set service to return list
this.output.push(output1);
this.output.push(output2);

// call a service and get its output
Const output = await this.factory.service.nsacrnm.ServiceIdentifier(inputToService);

// access the values of the output properties
const val1 = output[0].property1;
const val2 = output[1].property2;

Commands

Factory commands

To call a factory command, for example from a service, follow the structure below:

// Initialize the input 
const input = this.factory.entity.nsacrnm.FactoryCommandIdentifier_Input();
input.property1 = “value”;

// Access the repository of the specific root entity and choose the factory command
const rootEntityInstance = this.repo.nsacrnm.RootEntityIdentifier.FactoryCommandIdentifier(input)

// Access the id of the root entity instance
rootEntityInstance._id;

// Access the properties of the root entity instance
rootEntityInstance.property1;

Instance commands

To call a factory command, for example from a service, follow the structure below:

// Initialize the input 
// Access the repository of the specific root entity and choose the the factory command or search for a specific instance of the root entity
// Here we call a factory command
const rootEntityInstance = this.repo.nsacrnm.RootEntityIdentifier.FactoryCommandIdentifier(input)

// Initialize the input 
const input = this.factory.entity.nsacrnm.InstanceCommandIdentifier_Input();
input.property1 = “value”;

// From the returned root entity instance, it is possible to access the instance commands that are related ot this instance and execute them accordingly
rootEntityInstance.InstanceCommandIdentifier(input);

Repository Search

By ID

To search for a specific instance of a root entity that was already created by ID follow the structure below:

// Access the repository of the specific root entity and choose the FindById
const rootEntityInstance = this.repo.nsacrnm.RootEntityIdentifier.findById(id);

By Filter

To search for one or more instances of a root entity that were already created based on a specific filter follow the structure below:

// Access the repository of the specific root entity and choose the find
// Find takes two arguments: the first one is a Boolean indicated whether all children should be included in the filtering (true) or not (false)
const rootEntityInstance = this.repo.nsacrnm.RootEntityIdentifier.find(true, `name == ${name}`);

Errors

Throw Error

To throw an error use the following structure:

throw this.factory.error.nsacrnm.MyBusinessError();

Error handling

Business errors

To safely handle a business error that was modelled in the Solution Designer use the following structure:

try {
 
  (……)

  // This service will throw a business error
  await this.services.nsacrnm.ServiceIdentifier(input);

} catch (error) {

  if(this.isInstanceOf.businessError.nsacrnm.BusinessErrorIdentifier(error)){
     // In here “error” will be typesafe and one can access all of its properties
  }
  
}

Errors

These are the general errors that can occur. To safely handle an error, use the following structure:

try {
 
  (……)

  // This service will throw a business error
  await this.services.nsacrnm.ServiceIdentifier(input);

} catch (error) {

  if(this.isInstanceOf.error.GeneralError(error)){
     // In here “error” will be typesafe and one can access all of its properties
  }
  
}

Attention: The hierarchy of error consists of

GeneralError,
                        ValidationError

and BusinessError, where ValidationError and BusinessError extend GeneralError.

Reference a root entity

Reference root entity

To reference a root entity use the following structure:

// Initiate the reference and give as the id of the instance that is meant to be referenced
const reference = this.factory.reference.nsacrnm.RootEntityIdentifier(id);

// Load the specific instance
const rootEntityInstance = await reference.load();

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

// Now one can access the instance command that will manipulate the specific instance
rootEntityInstance.instanceCommandIdentifier();

List of root entity references

To use a list of root entity references as a property use the following structure:

// Initialize empty list
entityIdentifier.propertyIdentifier = [];

    
// Create new root entity references
const reference1 = this.factory.reference.nsacrnm.RootEntityIdentifier(id1);
const reference2 = this.factory.reference.nsacrnm.RootEntityIdentifier(id2);

entityIdentifier.propertyIdentifier.push(reference1);
entityIdentifier.propertyIdentifier.push(reference2);

Reference an external entity

To reference an external entity, use the following structure:

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

// Initialize the values of the constructor parameters
input.constructorProperty1 = “value1”;
input.constructorProperty2 = “value2”;

// Initiate the reference and call the constructor function while giving as input the values of the constructor properties
const reference = this.factory.reference.nsacrnm.ExternalEntityIdentifier(input);

// Load the specific instance
const extEntityInstance = reference.load();

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

// Validate the existence specific instance – this will return true or false
reference.validate();

List of external entity references

To use a list of external entity references as a property use the following structure:

// Initialize empty list
entityIdentifier.propertyIdentifier = [];

// Initialize the values of the external entity constructor parameters
const input1 = this.factory.entity.ExternalEntityIdentifier_Input();
input1. constructorPropertyIdentifier = “value1”;


const input2 = this.factory.entity.ExternalEntityIdentifier_Input();
input1.constructorPropertyIdentifier = “value2”;

    
// Create new external entity references
const reference1 = this.factory.reference.nsacrnm.ExternalEntityIdentifier(input1);
const reference2 = this.factory.reference.nsacrnm.ExternalEntityIdentifier(input2);

// Push external entity references to the property
entityIdentifier.propertyIdentifier.push(reference1);
entityIdentifier.propertyIdentifier.push(reference2);

Reference a local entity

To use a local entity as a property use the following structure:

// Craete a service input entity
const inputToService = this.factory.entity.nsacrnm.ServiceIdentifier_Input();

// Craete local entity object
const localEntity1 = this.factory.entity.nsacrnm.EntityIdentifier();

// Set entity properties
localEntity1.propertyIdentifier = ‘some property value’;

// Set local entity value as a service property value
inputToService.propertyIdentifier = localEntity1;

List of local entity references

To use a list of local entities as a property use the following structure:

// Craete a service input entity
const inputToService = this.factory.entity.nsacrnm.ServiceIdentifier_Input();

// Initialize service property (of type local entity list) to empty list
inputToService.propertyIdentifier = [];

// Craete local entity objects
const localEntity1 = this.factory.entity.nsacrnm.EntityIdentifier();
const localEntity2 = this.factory.entity.nsacrnm.EntityIdentifier();

// Set entity properties
localEntity1.propertyIdentifier = ‘some property value’;
localEntity2.propertyIdentifier = ‘some other property value’;


// Push local entities to the property list
inputToService.propertyIdentifier.push(localEntity1);
inputToService.propertyIdentifier.push(localEntity2);

Reuse types and classes from Solution SDK

Use Solution SDK Logger

import { Logger } from 'acronym_sdk';


public async execute(): Promise<void> {

  // call helper function with logger
  myUtil(this.util.log);
}

/**
 * utitlity function that needs a logger
 */
function myUtil(logger: Logger) {
  // use logger
  logger.info('myinfo');
}

Use CurrencyValue

import { CurrencyValue } from 'acronym_sdk';


public async execute(): Promise<void> {

  // call helper function with currency value from instance
  const newVal = setCurrencyCode(this.instance.myCurrProp);
}

/**
 * utitlity function that sets the currency of a currency value and returns the currency
 */
function setCurrencyCode(currencyVal: CurrencyValue, code: string): CurrencyValue {
  currencyVal.currency = code;
  return currencyVal;
}

Use Schemas and entities

import { schemas, entities } from 'acronym_sdk';

public convertSchemaToEntity(schema: schemas.ns2.Schema1): entities.ns1.Entity1 {
  // create a new entity and set schema values
  const e = this.factory.entity.ns1.Entity1();
  e.value1 = schema.value1;

  return e;
}

public convertEntityToSchema(entity: entities.ns1.Entity1): schemas.ns2.Schema1 {
  // create a new schema and set entity values
  const s = this.factory.schema.ns2.Schema1();
  s.value1 = entity.value1;

  return s;
}