@axway/ace-sdk

The ACE NodeJS SDK is used to create a microservice that is ready to be deployed into the ACE runtime

Service implemenation using the SDK

Implement the callback method

The callback method signature

Implement the callback method that will process the received message. Below is the signature of the method

function businessMessageProcessor(executionContext)

Execution Context

Get the Open Tracing Span Context

context = executionContext.getSpanContext();

Get the Business Message list

businessMsgs = executionContext.getBusinessMessages();

Get the Message Producer Function

msgProducer = executionContext.getMsgProducer();

Get a String Config Value

stringParamNameValue = executionContext.getStringConfigValue('stringParamName');

Get an Int Config Value

intParamNameValue = executionContext.getIntConfigValue('intParamName');

Get a Boolean Config Value

boolParamNameValue = executionContext.getBooleanConfigValue('boolParamName');

Input processing

The businessMsgs is an array of type ace.BusinessMessage. Each identify a business message and holds the payload and the metadata associated with the payload.

Processing payload

The payload can be retrieved using the interface method getPayload() on a ace.BusinessMessage object from the businessMsgs Array.

The payload [type ace.Payload] can be actual payload (use ace.Payload.getBody() to retrieve the content) or a reference to a location (use ace.Payload.getLocationReference() to identify if the payload body is location reference)

Processing metadata

The metadata can be retrieved using the interface method getMetaDataMap() on a ace.BusinessMessage object which returns map of string key/value pairs identifying the metadata associated with the payload.

Output processing

The output of the processing can be responded by generating new message(s). To create a new message construct business message and setup metadata. The new message can then be produced using msgProducer parameter.

Creating new ACE business message

• Construct the metadata

  Constructing the metadata is done by setting values using getMetaDataMap().set(key, value)

• Construct the payload

  Create the payload with content as demonstrated below. The newContent in the example below is a byte array holding the raw content

  let newPayload = ace.Payload();
  newPayload.setBody(newContent);
  

  OR

  Create the payload with location reference as demonstrated below. The newContent in the example below is a byte array holding the location reference.

  let newPayload = ace.Payload();
  newPayload.setBody(newContent);
  newPayload.setLocationReference(true);
  

• Construct the ACE business message

  Create new business message object as demonstrated below. The "newPayload" in the example below identifies payload for the new business message. MetaData may also be added.

  let newBusinessMessage = new ace.BusinessMessage();
  newBusinessMessage.setPayload(newPayload);
  newBusinessMessage.getMetaDataMap().set("md1", "md1-value")
  

Producing message

To produce messages use the Send method on msgProducer parameter as demostrated below

msgProducer.send(newBusinessMessage)

Add trace for service execution (Optional)

ACE SDK has instrumentation for OpenTracing(https://opentracing.io/specification/) built-in and provides ability to allow the business service to inject the tracing spans.

To start a span as child of span managed by ACE, use startSpanFromContext method from the ace package. Using the created span the business service can log details as demonstrated below.

let span = ace.tracing.startSpanFromContext(context, "business-service");
span.log("event", "processed message");
span.finish();

Add log lines (Optional)

ACE SDK sets up a logger object that can be used by the service to add additional logging to the console. Using the provided logger will write the lines consistent with the ACE SDK.

A call to the logger method and level will include a message and an optional object with 1 or many additional fields. The SDK provides field names that may be used.

ace.logger.debug("Starting business service", {[ace.fields.logFieldServiceName]: cfg.serviceName});

Handling errors in the service execution

ACE SDK had three error types defined.

SendingError - Can be returned from calling send method on the MsgProducer.

let error = msgProducer.send(newBusinessMessage);

ProcessingError - Returned by the businessMessageProcessor.

let simError = new ace.ProcessingError('processing error');
return simError;

SystemError - Returned by the businessMessageProcessor to clientRelay.

let simError = new ace.SystemError('system error');
return simError;

Register the service callback method with ACE

ACE business service must register the service info and callback method for making it usable as a step to build choreographies The service registration needs following details

• Service Name
• Service Version
• Service Type (optional)
  • NATIVE
  • AGGREGATION
• Service Description
• Callback method

The business service may also define config parameters to be used when using the service in a choreography. These parameters need to be added to the ServiceConfig object sent into registration

var serviceConfig = new ace.serviceCfg(serviceName, serviceVersion, serviceType, serviceDescription);

# String Parmeters (name, default value, isRequired)
let err = serviceConfig.addStringConfigParam('parameterName', 'defaultValue', false);
if(err) {
	# An error occurred adding the parameter
}

# Integer Parmeters (name, default value, isRequired)
let err = serviceConfig.addIntConfigParam('parameterName', 123, false);
if(err) {
	# An error occurred adding the parameter
}

# Boolean Parmeters (name, default value)
let err = serviceConfig.addBoolConfigParam('parameterName', false);
if(err) {
	# An error occurred adding the parameter
}

ace.register(serviceConfig, businessMessageProcessor, (link, error) => {
    if (error) {
        ace.logger.error(error);
        return;
    }
    // Start the link between the business message processor and linker
    link.start();
});

The provided template reads the serviceName, serviceVersion, serviceType, and serviceDescription from following environment variables respectively, but it's the implementation choice on how to setup these details.

• SERVICE_NAME
• SERVICE_VERSION
• SERVICE_TYPE
• SERVICE_DESCRIPTION

If the environment variable is not set it will read them from the package.json file when the service is started via npm.