In EMG 7.2.4 we took the first step towards microservices by adding support for calling plugins over HTTP. In 7.2.6 we took the next step by adding a new section type in the server.cfg configuration file, called SERVICE. The basic motivation is the same as for a plugin, as it creates a way for EMG administrators to add site specific business logic on their own.
Similarly to the PLUGIN sections, these new sections supports the parameters URL and INSTANCES, with the same meanings. For the URL, both the “URL=url” syntax and the “URL=|url1|url2|…|” syntax are supported. In both cases the url is the base address used in the request. For each supported use case, a suffix is added to the path component, making it possible to use the same microservice for multiple use cases. No additional configuration parameters are supported at this time, but may be added in later versions. The possible values for the INSTANCES parameter depend entirely on the microservice implementation, and is 1 by default.
In contrast to a plugin, these microservices can only be called over HTTP. There is not, and will never be, a way to run this code within the emgd process. They can not yet be defined using EMG Portal.
Credit services
The emguser.charge_balance column serves two purposes. First, it keeps track of the current credit balance for the user, which is adjusted for each processed message. Second, its value is used to determine whether new messages can be sent, assuming the emguser.allowpostpaid column is not true. The exact balance is actually not used by EMG, it just has to be larger than the number of pdus in the message multiplied by the value of the DEFAULT_CHARGE option.
An EMG administrator may want to provide some additional logic for the credit management. For example, it may be useful to store all balance updates into a specific audit log or to store the balance in another system or database. The new microservice mechianism can be used both for these cases and anything else that is needed. As long as the emguser.charge_balance is sufficiently large when the user can send more messages, and set to 0 otherwise, this will work just fine.
Starting with EMG 7.2.6, the database profile used to locate the emguser entry can now have an additional CREDIT_SERVICE parameter. The value of this field is a microservice name, as defined above. Each update of the charge_balance field will now instead be performed using the specified microservice. If the request fails for some reason, the update is instead done directly in the database, just as before.
The request to the microservice will be a POST, the URL path will be appended with “/credits/update”, and the http body will be a json structure. The fields in this structure are as follows. Please note that both adds and subs are positive expressions. The exact format of the expressions may vary between EMG releases.
userid | The value of the emguser.userid column. |
column | The name of the column to update. This is “charge_balance” for normal SMS traffic. |
adds | A string containing an expression to add to the column. |
subs | A string containing an expression to subtract from the column. |
A good starting point when implementing this service is to convert it to a normal SQL statement, updating the normal EMG database. The SQL could then be constructed like so: “UPDATE emguser SET $column = $column $adds – ($subs) WHERE userid = $userid”. If the connector option BATCH_USER_UPDATES is set, the adds and subs field can contain several hundred terms each.