An exchange rate plugin is a collection of PHP scripts that implements set of operations. Communication pattern is displayed in the picture below.
Components from this picture are explained further in this section.
Exchange Rate Provider
Exchange Rate Provider is an APS application with UI screens embedded to UX1. This application is CloudBlue Commerce integration point for Exchange Rate SDK and all exchange rate plugins.
Exchange Rate SDK Component
Exchange Rate SDK is a microservice with internal Apache web server process which hosts php-based exchange rate SDK with plugins. Within this instance, a single index.php script:
-
Receives HTTPS requests from the Exchange Rate Provider component,
-
Detects for each of those requests which plugin and method should be invoked,
-
Dispatches that request to the detected pair: plugin - method.
The index.php script also ensures conversion of request and response data from JSON to PHP arrays and back. A plugin function takes an array of parameters, if there are any, and returns an array with result data.
Open Exchange Rates Plugin
Open Exchange Rates is a pre-installed plugin that is added with the Exchange Rates SDK component.
Each plugin is a folder that contains a special structure (see Location and Naming Convention). The plugin script file (the one that has the same name as the folder) implements all required methods using the following method name convention: $(PLUGIN_NAME)_$(METHOD_NAME). For example, the OpenExchangeRates plugin must implement the GetConfig method in the OpenExchangeRates.php script using the following method name: OpenExchangeRates_GetConfig. Not following this convention causes integration errors in plugin capabilities. For a list of methods that a plugin should implements, see API Specification.
Once a plugin receives a request, it can execute whatever PHP5 code it needs to process that request. If communication with a 3rd party exchange rate provider API is mandatory to process the request, the plugin can use any communication schema, for example, REST, and data format, for example, JSON. The plugin method for response, however, must be an associative array and must contain several mandatory keys. See each method description for details.
To install a new plugin, you need to copy the plugin folder to a special directory, that is, /custom inside the Exchange Rate SDK component pod. For details, see Plugin Installation.
A plugin developer must be aware that:
- Plugins are always passive in their communication with CloudBlue Commerce.
- Plugins do not need to store any configuration parameters or transactional data themselves. Configuration is stored at the invoking side (Exchange Rate Provider) and is passed as input parameters to a plugin method.
- Plugins do not need to write logs to file system directly; CloudBlue Commerce provides special utility functions for that purpose.
Overall, the communication between CloudBlue Commerce and a plugin is organized as explained in the diagram below.
