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)
- 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.