SMARTKORPOR EXPORT INTEGRATION DEPLOYMENT GUIDE
This is a validation and export integration without amendments or cancellations to SmartKorpor in Sierra Leone, using SLE as the currency. The Utility Bill transfer type is implemented.
Validation is realtime, triggered during transaction submission.
The export is non-realtime, executed by a cron schedule.
IP address whitelisting is not required.
Prerequisites
The client must provide the "Key", "Client ID" and "Secret" for the API.
The client must do some basic setup on their production system (send the message below to the client)
Dear ...,
In order to prepare the SmartKorpor integration for deployment to production, could you please do the following on your production system and inform us once done.
1. Login to ARM as an admin and add Sierra Leone as a destination country (ensuring the currency code is SLE, not SLL), if it's not already present in the list of destination countries.
2. Ensure commission slabs exist for Sierra Leone.
3. Create a new processing bank in Sierra Leone, including delivery bank.
The abbreviated processing bank name and bank code should be "SMARTKORPOR-SL".
You can create additional delivery banks if you require.
4. Create Utility Companies for Sierra Leone from Settings > Delivery Entities.
The Company Code should be "SMARTKORPOR-SL".
Kind regards,
Deployment Steps
5. Check that the client has done the basic setup correctly.
6. Add the following configuration to custom/config/config_3rdparty.json, following the instructions in the comments as necessary. You can ignore any additional configuration option you may find, such as master_api_key or agency_code.
"CONFIG_SMARTKORPOR": {
"enabled": true,
"processing_bank_prefix": "SMARTKORPOR-",
"processing_bank_abbrev_name": "SMARTKORPOR-SL",
"rest_client": {
"api_environment": "test", //test or live
"rest_uri_live": "https://app.smartkorpor.com/api/",
"rest_uri_test": "https://app.smartkorpor.com/api/",
"key": "", //USE CLIENT PROVIDED VALUE HERE
"client_id": "", //USE CLIENT PROVIDED VALUE HERE
"client_secret": "", //USE CLIENT PROVIDED VALUE HERE
},
"allowed_trans_types": [
"Utility Bill",
],
"export_cron_frequency": "*/5 * * * *",
"error_notification_from_email": "SmartKorpor@integration.com",
"error_notification_to_email": "errors@post.remitone.com"
}
7. We need to enable the UtilityBillCompanyRouter if it's not already enabled. Check by running "vim runtimeconfig/config_routing.php". It should be under ROUTING_CONFIG->chain and not commented out.
If it is commented out, run "vim custom/config/config_routing.json" to edit the routing, and ensure it is added as follows.
{
"ROUTING_CONFIG":{
"chain":[
...
"UtilityBillCompanyRouter",
]
}
}
8. In custom/config/config_state_machine.json we want to add "SMARTKORPOR-" to "BANKS_TO_HQOK" listed under the "modify_state_machine" config block, resulting in something like:
{
"STATE_MACHINE_CONFIG": {
"state_machine": { ... },
"transaction_groups": { ... },
"modify_state_machine": {
"BANKS_TO_HQOK":[
// uncomment the following line to create rules based on the prefix
"SMARTKORPOR-"
],
}
}
}
9. Ensure Settings > System Configuration Settings > CONFIG_FORMS_BASE > default > "trans_new.benef_utilitybillaccountno.display" has a value of true, or "trans_new.benef_utilitybillinvoice.display" has a value of true.
10. In custom/config/config_notification.json add "remitone\\integration\\SmartKorpor\\SmartKorporValidateTransactionSubscriber" to the NEW_TRANSACTION event under realtime_subscriptions.
{
"CONFIG_NOTIFICATION":{
"realtime_subscriptions": {
"NEW_TRANSACTION": [
"remitone\\integration\\SmartKorpor\\SmartKorporValidateTransactionSubscriber",
// ...
],
// ...
},
// ...
},
// ...
}
11. Run 'php bin/console app:update-system' or 'php bin/console scripts/config-update' from the terminal to load all the config changes
12. The scheduled cron job to export s should be added automatically by Crunz, and can be manually executed from the terminal by "php bin/integration smartkorpor:export"
If the cron job is not added (verify by executing 'crontab -l' from the terminal), add the cron job manually by running 'crontab -e' and adding the following to the bottom of the crontab:
Note: "/THE-HOME-PATH/" refers to the full path to the project folder, eg /home/{username}/{project-folder .. mtstest, mtms, etc}/, so replace as appropriate
#SMARTKORPOR
*/5 * * * * cd /THE-HOME-PATH/crons; /usr/bin/flock -n /THE-HOME-PATH/custom/tmp/smart_korpor_export.lock /usr/bin/php ./smart_korpor_export.php >/dev/null 2>&1
The cron job runs every five minutes. A log file will automatically be generated at logs/smart_korpor.log
13. Verify that the logs are being written, and if not, cd into the logs directory and run "ls -la" to check that the owner of smart_korpor.log is the logged in user, the group is apache, and read-write permissions are set.
If corrections are needed, cd into the scripts directory and run "sh fixpermissions.sh". If the permissions on the log file aren't corrected automatically, you may try the chmod command for updating the read-write permission, the chown command to change the owner to the logged in user, and the chgrp command to change the group to apache
14. Since sometimes a utility bill invoice number is needed, and sometimes a utility bill account number is needed, and sometimes both, we need to update CONFIG_FORMS_BASE > default to include the following values:
"trans_new.benef_utilitybillaccountno.display": true,
"trans_new.benef_utilitybillaccountno.required": false,
"trans_new.benef_utilitybillinvoice.display": true,
"trans_new.benef_utilitybillinvoice.required": false,
15. Payonlime (the client we did the integration for in the first instance) have an existing text override on the account number field, so run "vim edit custom/libs/texts/lang.en.overrides" from the terminal and edit the override value in the return array to be 'label.entity.transaction.beneficiary_utilitybillaccountno' => 'Meter/Account No.',
This includes the ARM, ORM and RWS.
for any overrides. If you change anything in point 1 and it doesn't reflect on the apps/ORM then you will need to change it here as well.
. "Country Name-Destination" for the ARM , "ORM-Country Name-Destination" for the the ORM/apps. "Country Name" for the source country. "Country Name" will be the exact spelling you use for said country in the Destination/Source country list.