TypeScript solution framework (SDK)

This is used to create an entity object (of all types including input and output entities). If this is assigned to a variable, then the variable will contain all the properties and commands that belong to the specific entity. The properties of the variable are editable.

// Create an Entity using entity factory
const entity1 = this.factory.entity.nsacrnm.Entityidentifier();
// Access entity1 properties
entity1.propIdentifier = 'some property value';

This is used to create a new business error that can be thrown to the user.

// Create an error using error factory
const error1 = this.factory.error.nsacrnm.ErrorIdentifier();

// Access error1 properties
error1.errorDescription = 'Some Error Description';
error1.errorMessage = 'Some Error Message;

This is used to create a reference to an external entity or a root entity on the same or a different namespace inside the solution. If referencing external entities, this component calls the constructor, and it returns the created instance of the external entity. If referencing other aggregates, it returns the instance that is being referenced. In both cases the returned values are read-only.

// Create an entity reference for root entity using reference factory
const ref1 = this.factory.reference.nsacrnm.RootEntityIdentifier(someEntityId);

// Load referenced entity
const rootEntity = await ref1.load();

// create a reference to an external entity that takes an input

// Create input object via factory
const input = this.factory.entity.cptest.ExternalEntityIdentifier_ConstInput();
input.propertyIdentifier = 'Some property value';

This calls the constructor method of the external entity. It 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.

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

// Access the associated properties 
extEntity.assProp1;

// Load external entity - no input needed
extEntity.load();

// Validate external or update local - no input needed
extEntity.validate();

This is used to create an event. It returns empty properties that belong to the payload and the publish function in order to trigger the event. The properties of the payload are editable. The properties and the values assigned to them will be the input of the agent that is called after triggering the event.

// Create an event using event factory
const event1 = this.factory.event.nsacrnm.EventIdentifier();
 
// create event payload using entity factory
const payoad = this.factory.entity.nsacrnm.EntityIdentifier();
 
// set payload properties
payload.propIdentifier = 'some property value';
 
// Set event payload
event1.payload = payoad;
 
// publish event
await event1.publish();

This is used to create schema objects. It returns the properties that belong to the schema (i.e. the entire schema object/array/oneOf). The properties returned are editable. This is accessible from operation scripts and .test.ts files of operations.

// Create a schema using schema factory
const schema1 = this.factory.schema.nsacrnm.SchemaIdentifier();
 
// Access schema1 properties
schema1.propIdentifier = 'some property value';

A more detailed description of filter expressions is available at filter expressions

In the implementation file of a service, command, agent and operation entity instance check can be done through isInstanceOf functionality, the entity instance check will also check for the entity hierarchy.

// check an object
if (this.isInstanceOf.entity.ns1.BlueCar(car)) {
    // now one can access the special property that only blue car has
    const prop = car.specialPropOfBlueCar;
}

// check BlueCar is a Car (Since BlueCar is a child of Car, the entity instance check will also check for the entity hierarchy)
if (this.isInstanceOf.entity.ns1.Car(blueCar)) {
      // now one can access the special property that only car has
      const prop = blueCar.specialPropOfCar;
}

In the implementation file of a service, command, agent and operation error instance check can be done by using isInstanceOf functionality, thus enable to code handling logic for different error instances

try {
      // try some logic
} catch (e) {

      // check for GeneralError
      if (this.isInstanceOf.error.GeneralError(e)) {
        // now can handle this general error
      }

      // check whether the validation of an entity (used as input or instance) fails
      if (this.isInstanceOf.error.ValidationError(e)) {
        // now can handle this validation error
      

      // check for a child of abstract BusinessError
      if (this.isInstanceOf.error.BusinessError(e)) {
        // now can handle this Business error
      }

      // check whether an  action (e.g. a command) is not currently available
      if (this.isInstanceOf.error.ActionNotAvailableError(e)) {
        // now can handle this ActionNotAvailable error
      }

      // check whether an aggregate is found in the datastore
      if (this.isInstanceOf.error.AggregateNotFound(e)) {
        // now can handle this AggregateNotFound error
      }

      // check whether an external request (i.e. this.util.request) caused an error
      if (this.isInstanceOf.error.ExternalRequestError(e)) {
        // now can handle this ExternalRequest error
      }
     
      // check whether an internal request caused an error
      if (this.isInstanceOf.error.InternalRequestError(e)) {
        // now can handle this InternalRequest error
      }
}

try {
      // try some logic
} catch (e) {
      // check whether the error matches any of the errors modelled in Solution Designer      
      if (this.isInstanceOf.businessError.ns1.NoBalanceAvailable(e)) {
        // now can handle this specific business error
      }

      if (this.isInstanceOf.error.ValidationError(e)) {
        // now can handle this validation error
      }

      if (this.isInstanceOf.businessError.ns2.NoCustomerFound(e)) {
        // now can handle this specific business error
      }
}

// call operation "getPets" in integration API "petstore"
const result = await this.apis.petstore.getPets();

If path parameters or query parameters are defined, the function offers the possibility to set these parameters which are identified by the name. The values of the path parameters as well as the query parameters are expected to be JavaScript objects where each key is the name of the parameter. The URL and ca_certs are used automatically according to the specification.

// findPets by owner (pathParameter) and filter by status and age (queryParameter)
const result = await this.apis.petstore.getPetsOfOwner({
  owner: 'MyOwner'
}, {
  status: 'alive',
  age: 5
});

If a request body is defined for the operation, the function offers the possibility to set the request body as a JavaScript object.

// add new pet using "pet data" (request body)
await this.apis.petstore.addPet({
  owner: 'MyOwner',
  status: 'alive',
  age: 1
});

The result of the operation always consists of the status code and the actual response data. Both are returned from the operation call.

try {
  const result = await this.apis.petstore.getPets();
  // read result depending on status code
  if (result.status === 200) {
    // everything is good --> read data
    const pets = result.data;
    console.log(pets[0].status);
  }
} catch (e) {
  // handle error
  this.util.log.error(e.message);
  throw e;
}

This is used to give access to the request path parameters of an operation.

// access operation request path parameters
const val = this.request.path.pathParamIdentifier;

This is used to give access to the request query parameters of an operation.

// access operation request query parameters
const val = this.request.query.queryParamIdentifier;

This is used to give access to the request body of an operation. If the request body is a simple type (i.e. integer, number, string etc.) then the value is accessed immediately. Otherwise, in case the body is an object, the command is expanded to access each property. In case that the body is an array type, then the body can be treated similarly to a JavaScript array.

// access operation request body
const body = this.request.body;
const val = this.request.body.popertyIdentifier;

This is used to access the response status of an operation. The value only takes the values that have been modelled in the Solution Designer.

// set response status to be returned
this.response.status = 200;

// access operation response status
const status = this.response.status;

This is used to access the response body of an operation to the user. If the body is a primitive type schema, then a value can be directly accessed / assigned. Otherwise, the body must be initialized to its corresponding schema type ( using the schema factory component) and then each property should be initialized accordingly.

// initialize response body via schema factory
const body = this.factory.nsacrnm.schema.schemaIdentifier();

// set operation response body
this.response.body = body;
const val = this.response.body.popertyIdentifier;

This is used to access the values of the response headers of an operation.

// access operation request body
const headers = this.response.headers;