Documentation

Description

The Amadis Configuration Module provides an integrator with easy access to Nexo TMS related functionalities.

Goal and usage

This module’s main functionality is to retrieve a configuration from a compatible Nexo TMS host, and translate into Arkos Framework’s configuration format. In Java land, this configuration is represented as a generic byte array (byte[]) containing the entire configuration structure as TLV fields.

This configuration then becomes the integrator’s application responsibility. The Arkos Framework functionalities generally requires this configuration to be provided - however, other uses (including persistance) are left to the integrator.

How to?

Initialise a connection provider

This refers to a different module - a more complete documentation can be found at Unified Connection Provider

For all usages of the Configuration Module, a Connection Provider must be available. A default implementation with Nexo required capabilities is provided.

// Provide an input stream to the Certificate Authorities allowed on this provider
InputStream nexoCAFile = { ... };

// Initiate an instance of an Object implementing the TMSConnectionProvider interface
// We are using the Amadis provider here for ease of use
AmadisUnifiedConnectionProvider connectionProvider = AmadisUnifiedConnectionProvider.DefaultNexoProvider(nexoCAFile);

Force a configuration attempt on a specific host

This should be used for the first configuration retrieval, or to force a specific host different from what was specified in the configuration

In the case where no configuration is previously available, a basic configuration must be created prior to any configuration attempt. It must contain the following TLV DO:

TerminalConfiguration(0xFF01) containing POIID(0xDF9F32)
Ex: FF01C0DF9F3208504f494944303031

If using the AmadisTLV helpers, this can be achieved with:
TlvTree configTree = TlvTree.Empty();
TlvTree terminalConfig = configTree.AddChild(ConfigurationTags.TerminalConfiguration);
terminalConfig.AddAscii(ConfigurationTags.POIID, "POIID001");
arkosConfiguration = configTree.AsBytes();

// Load or initialise an empty configuration - see the [Minimal Configuration Required] section for more information

// Ex: TerminalConfiguration(0xFF01) containing POIID(0xDF9F32)

// Hard mode:
byte[] configuration = { (byte) 0xFF, 0x01, 0xC0, 0xDF, 0x9F, 0x32, 0x08, 0x50, 0x4f, 0x49, 0x49, 0x44, 0x30, 0x30, 0x31 };

// If using the AmadisTLV helpers, the same can be achieved with:
TlvTree configTree = TlvTree.Empty();
TlvTree terminalConfig = configTree.AddChild(ConfigurationTags.TerminalConfiguration);
terminalConfig.AddAscii(ConfigurationTags.POIID, "POIID001");
arkosConfiguration = configTree.AsBytes();

// Execute the configuration action
ConfigurationResult result = AmadisTMSModule.DoConfiguration(connectionProvider, configuration, "hostname:port");

// Inspect and use the result Object
if (result.isSuccess()) {
    Log.d("config", "Configuration attempt was successful");
    
    // Configuration attempt was successful - this is the new valid configuration and should replace the old one.
    configuration = result.getConfiguration();

    // It is important to always keep the Connection Provider up to date with the current configuration
    connectionProvider.setConfiguration(configuration);
}
else {
    // The textual reason for a failure is provided
    Log.d("config", "Configuration attempt failed: " + result.getError());
}

Execute a configuration attempt, using the system-configured TMS host

This should be used for any subsequent manually triggered configuration retrieval. It uses the configuration content’s host system to identify the active TMS host, then proceeds to retrieve the configuration if required.

// [configuration] must be a previously received valid configuration from the TMS system
ConfigurationResult result = AmadisTMSModule.DoConfiguration(connectionProvider, configuration);

// Inspect and use the result Object
if (result.isSuccess()) {
    Log.d("config", "Configuration attempt was successful");
    
    // Configuration attempt was successful - this is the new valid configuration and should replace the old one.
    configuration = result.getConfiguration();

    // It is important to always keep the Connection Provider up to date with the current configuration
    connectionProvider.setConfiguration(configuration);
}
else {
    // The textual reason for a failure is provided
    Log.d("config", "Configuration attempt failed: " + result.getError());
}

Trigger a Configuration Module managed cyclic call

This is not supported in the current version.

Details TBD