Subscriber and Wallet Data
Subscriber and Wallet Data
Overview
The Logic Node exposes all available subscriber and wallet data for use within your scripts, giving you the power to directly manipulate and query this information.
Subscriber data is never cached by the Lua runtime. However, the NCC framework may decide internally to return cached information if it determines that no changes have taken place - for example, if you perform two wallet information requests without any wallet update request between them. There is no way to avoid this caching of information by NCC.
Subscriber Data
Wallet Data
Wallet Updates
Utility Functions
If the cli provided is not a numeric string: If the response from the node is not parseable: The primary and secondary wallet information fields are only returned if the subscriber has wallets of that type.
▲ ccs.subscriber_for_cli (cli)
Parameters
cli
The MSISDN/CLI of the subscriber to retrieve information for.
Returns
Either nil if the subscriber was not found, or a table of subscriber information, formatted as:
{
ACS_CUST_ID = <CCS_ACCT_REFERENCE.ACS_CUST_ID>
ACS_CUST_NAME = <ACS_CUSTOMER.NAME>
ACCT_REF_ID = <CCS_ACCT_REFERENCE.ACCT_REF_ID>
CLI = <CCS_ACCT_REFERENCE.CLI>
ACCOUNT_NUMBER = <CCS_ACCT_REFERENCE.ACCOUNT_NUMBER>
primary [OPTIONAL] = {
BE_ACCT_ID = <CCS_ACCT.BE_ACCT_ID>
BE_ACCT_ENGINE_ID = <CCS_ACCT.BE_ACCT_ENGINE_ID>
ACCOUNT_NUMBER = <CCS_ACCT.ACCOUNT_NUMBER>
ACCT_CURRENCY_ID = <CCS_ACCT.CURRENCY_ID>
ACCT_TYPE_ID = <CCS_ACCT_TYPE.ID>
ACCT_TYPE_NAME = <CCS_ACCT_TYPE.NAME>
WALLET_TYPE_ID = <CCS_WALLET_TYPE.ID>
WALLET_TYPE_NAME = <CCS_WALLET_TYPE.NAME>
}
secondary [OPTIONAL] = {
<same fields as primary>
}
}
Errors
If no cli is provided:
CLI must be provided.
Subscriber CLI must be a numeric string.
Retrieved subscriber information is not readable.
Usage
This function queries the Lua runtime and extracts the subscriber information for the given CLI/MSISDN from the SLC database.
local cli = '12345'
local pcs
local s = ccs.subscriber_for_cli (cli)
if (s) then
-- subscriber exists; get information for their service provider
pcs = ccs.customer.periodic_charges (s.ACS_CUST_ID)
else
error ("Subscriber " .. cli .. " does not exist!")
end
▲ ccs.subscriber ()
Parameters
None.
Returns
As for ccs.subscriber_for_cli.
Errors
As for ccs.subscriber_for_cli.
Usage
This is a shorthand version of ccs.subscriber_for_cli that queries for the current logical subscriber.
local sub = ccs.subscriber ()
if (s.secondary) then
-- logical subscriber has secondary wallet
end
If the retrieved wallet information is not parseable:
▲ ccs.wallet.get ()
Parameters
None.
Returns
Either nil if no wallet was returned, or a table of wallet information, formatted as:
{
ID = <wallet ID>
TYPE_ID = <wallet type ID for customer>
PRODUCT_ID = <product type ID for the active wallet>
CATEGORY = <Primary|Secondary>
}
Errors
If the active domain has insufficient capabilities for the getWallet action:
Insufficient capabilities for 'walletInfo' action.
Retrieved wallet is not readable.
Usage
This function performs the getWallet chassis action and returns the information for the active wallet for the logical subscriber.
local w = ccs.wallet.get ()
if (w and w.CATEGORY == 'Secondary') then
-- logical subscriber is using their secondary wallet
end
If the cli provided is not a numeric string: If the active domain has insufficient capabilities for the alternateWalletDetails action: If the retrieved wallet information is not parseable:
▲ ccs.wallets.get (cli)
Parameters
cli
The MSISDN/CLI of the subscriber to retrieve information for.
Returns
Either nil if no wallet was returned, or a table of wallet information, formatted as:
{
PRIMARY = <wallet type name>
SECONDARY = <wallet type name>
}
Errors
If no cli is provided:
CLI must be provided.
Subscriber CLI must be a numeric string.
Insufficient capabilities for 'alternateWalletDetails' action.
Retrieved wallet is not readable.
Usage
This function performs the alternateWalletDetails chassis action and returns the (somewhat limited) information for the CLI specified.
local ws = ccs.wallets.get ('12345')
if (w and w.PRIMARY == 'Primary') then
-- quelle surprise
end
If the retrieved wallet information is not parseable: If no base wallet information is returned from the node: If no wallet balance information is returned from the node:
▲ ccs.wallet.info ()
Parameters
None.
Returns
Either nil if no wallet was returned, or a table of wallet information, formatted as:
{
EXPIRY = <wallet expiry date (epoch) or nil>
LAST_ACCESSED = <wallet last access date or nil>
ACTIVATION_DATE = <wallet activation date (epoch) or nil>
MAX_CONCURRENT = <wallet maximum concurrent accesses>
NUM_BALANCES = <number of balances in the wallet>
USER_CURRENCY_ID = <wallet user currency ID>
SYS_CURRENCY_ID = <wallet system currency ID>
STATE = <wallet state (single character)>
BALANCES = {
<balance ID> = {
ID = <balance ID>
UNIT = <balance unit type ID>
MAX_CREDIT = <balance maximum credit or nil>
EXPIRY = <balance expiry date (epoch) or nil>
SYSTEM_VAL = <total balance amount in system currency (littles)>
USER_VAL = <total balance amount in system currency (littles)>
SYSTEM_VAL_UNRES = <unreserved SYSTEM_VAL>
USER_VAL_UNRES = <unreserved USER_VAL>
LIMIT_TYPE = <limit type, one of LIMITED_POSTPAID, POSTPAID, PREPAID,
SINGLE_USE_PREPAID, or UNKNOWN>
}
<balance ID> = ...
}
}
Errors
If the active domain has insufficient capabilities for the walletInfo action:
Insufficient capabilities for 'walletInfo' action.
Retrieved wallet info is not readable.
No base wallet info returned.
No wallet balance info returned.
Usage
This function performs the walletInfo chassis action and returns the information for the active wallet for the logical subscriber.
local acs_cust_id = ncc.engine.acs_customer ()
local wi = ccs.wallet.info ()
for k, v in pairs (wi) do
if (k == 'BALANCES') then
for bk, bv in pairs (v) do
bname = ccs.customer.balance_type_name_for_id (acs_cust_id, bk)
for bkx, bvx in pairs (bv) do
if (bkx == 'LIMIT_TYPE') then
ncc.debug ("Subscriber's " .. bname .. " limit type is " .. bvx)
end
end
end
end
end
If the retrieved wallet information is not parseable: If no base wallet information is returned from the node: If no wallet balance information is returned from the node: If no wallet bucket information is returned from the node: If bucket information is found for a balance type that is not in the balance information: If bucket information for a balance type is not parseable:
▲ ccs.wallet.extended_info ()
Parameters
None.
Returns
Either nil if no wallet was returned, or a table of wallet information, formatted as per ccs.wallet.info but with bucket information as well:
{
...
BALANCES = {
<balance ID> = {
...
BUCKETS = {
<bucket ID> = {
ID = <bucket ID>
VAL = <bucket value in system currency (littles)>
EXPIRY = <bucket expiry date (epoch) or nil>
REF = <subscriber reference or nil>
START = <bucket start date (epoch) or nil>
}
<bucket ID> = ...
}
}
<balance ID> = ...
}
}
Errors
If the active domain has insufficient capabilities for the extendedWalletInfo action:
Insufficient capabilities for 'extendedWalletInfo' action.
Retrieved wallet info is not readable.
No base wallet info returned.
No wallet balance info returned.
No wallet bucket info returned.
Bucket information found for missing balance type <balance type>.
Retrieved bucket info is not readable for balance type <balance type>.
Usage
This function performs the extendedWalletInfo chassis action and returns the information for the active wallet for the logical subscriber.
local extendedWalletInfo = ccs.wallet.extended_info ()
local balance = ccs.wallet.get_balance (extendedWalletInfo, 123)
local bucket = nil
if (balance) then
for k, v in pairs (balance) do
if (type (v) == 'table' and k == "BUCKETS") then
for bk, bv in pairs (v) do
if (type (bv) == 'table') then
bucket = bv
break;
end
end
if (bucket) then break end
end
end
end
At least one of the first three fields must be set. Unexpected values in the table will be ignored, so the results of a ccs.wallet.info call can be updated and returned in an update. However, any values specified in the table will be sent in the update action as changes.
If no wallet update information is provided: If there is no state, last access, and activation date information in the wallet table: If the wallet update status returned from the thread is not readable:
▲ ccs.wallet.update (wallet)
Parameters
wallet
A (limited) table of values, similar to the return value of ccs.wallet.info:
{
LAST_ACCESSED = <wallet last access date or nil>
ACTIVATION_DATE = <wallet activation date or nil>
STATE = <wallet state (single character) or nil>
CREATE_EDR = <0 = no, anything else = yes>
}
Returns
true if the update was successful, otherwise false.
Errors
If the active domain has insufficient capabilities for the walletUpdate action:
Insufficient capabilities for 'walletUpdate' action.
Table of values must be provided for wallet update.
At least one value must be changed for a wallet update.
Wallet update status is not readable.
Usage
This function performs the walletUpdate chassis action and submits the provided information as an update for the active wallet for the logical subscriber. If no errors occur, the status of the update is returned as either true or false.
local wu = { }
wu.STATE = 'S'
wu.LAST_ACCESSED = os.time () - 86400
-- note that this will be reset by any other action
wu.ACTIVATION_DATE = os.time () - (86400/3)
wu.CREATE_EDR = 1
ncc.debug ("Sending wallet update as:")
ncc.debug (wu)
local r = ccs.wallet.update (wu)
if r then
-- wallet updated successfully
end
At least one of the first three fields must be set. Unexpected values in the table will be ignored, so the results of a ccs.wallet.info can be updated and returned in an update. If more than one balance type is specified, each balance will be sent as a separate update. Any state or start date change(s) will be sent with the first balance update. The bucket ID, expiry, and start date fields are optional and should only be altered if you’re sure you know what you’re doing.
If no subscriber information can be retrieved: If no wallet update information is provided: If there is no state, start date, or balances in the wallet table: If the wallet table has balances that are not in a table: If any balance type has a non-numeric balance type ID: If any balance value has a non-numeric value: If the wallet update status returned from the thread is not readable: Note: Setting a bucket expiry of 0 will cause a bucket to never expire, even if a subsequent expiry date is re-applied. This is the inbuilt internal behaviour of the NCC platform.
▲ ccs.wallet.extended_update (wallet, lookup_info)
Parameters
wallet
A (limited) table of values, similar to the return value of ccs.wallet.extended_info:
{
START_DATE = <wallet start date (epoch) or nil>
STATE = <wallet state (single character) or nil>
BALANCES = {
<balance ID> = {
ID = <balance ID, mandatory>
SYSTEM_VAL = <total balance amount
in system currency (littles), mandatory>
BUCKET_ID = <ID to assign bucket, optional)>
SUB_REF = <subscriber reference, optional>
BUCKET_EXP = <bucket expiry date (epoch), optional>
BUCKET_START = <bucket start date (epoch), optional>
}
-- OR
<balance ID> = <total balance amount
in system currency (littles)>
-- (other fields defaulted in this syntax)
}
EXTRA_INFORMATION = <TAG=VALUE, pipe-separated>
}
lookup_info
A table of subscriber lookup information. Optional; will be automatically retrieved if not provided.
Returns
true if the update was successful, otherwise false.
Errors
If the active domain has insufficient capabilities for the extendedWalletUpdate action:
Insufficient capabilities for 'extendedWalletUpdate' action.
Unable to retrieve logical subscriber information.
Table of values must be provided for wallet update.
At least one value must be changed for a wallet update.
If provided, wallet balances must be a table for a wallet update.
Invalid balance ID <balance type ID> provided for wallet update.
Invalid balance value <balance type value> provided for wallet update.
Wallet extended update status is not readable.
Usage
This function performs the extendedWalletUpdate chassis action and submits the provided information as an update for the active wallet for the logical subscriber. It allows direct bucket replacement and creation. If no errors occur, the status of the update is returned as either true or false.
-- simple addition of $10.00 to logical subscriber
local wu = { BALANCES = { ['147'] = 1000 } }
ccs.wallet.extended_update (wu)
-- using values as returned by wallet info
local delta = 2000
wu = {
MAX_CONCURRENT = 15,
EXPIRY = 1473849547,
USER_CURRENCY_ID = 1,
BALANCES = {
[147] = {
ID = 147,
BUCKET_EXP = 1418501215,
SYSTEM_VAL = delta
}
},
NUM_BALANCES = 6,
EXTRA_INFORMATION = "FOO=BAR|RHU=BARB",
SYS_CURRENCY_ID = 1,
LAST_ACCESSED = 1415907954,
ACTIVATION_DATE = 1415831938,
STATE = 'A'
}
ncc.debug ("Doing extended wallet update with:")
ncc.debug (wu)
local r = ccs.wallet.extended_update (wu)
if not r then
-- wallet extended update failed
end
If subscriber information cannot be retrieved for the logical subscriber: If no extended wallet information can be retrieved for the logical subscriber: If no wallet information can be retrieved for the logical subscriber: You can fill the table used in this function up yourself, either totally or partially, and the NCC API functions that use it will use the data you provided rather than get fresh copies. For the most part, this function can be ignored; it will be used automatically where required.
▲ ccs.wallet.fill_lookup_info (lookup_info)
Parameters
lookup_info
Either nil or a fully- or partially-populated table of results the same as this function returns.
Returns
Retrieved subscriber, wallet, and customer information in this format:
{
FILLED = <true|false, added by this function for speed>
SUBSCRIBER = <subscriber definition from ccs.subscriber ()>
EXTENDED_WI = <wallet information from ccs.wallet.extended_info ()>
WALLET = <wallet information from ccs.wallet.get ()>
PERIODIC_CHARGES = <periodic charge information for SUBSCRIBER.ACS_CUST_ID
from ccs.customer.periodic_charges ()>
}
Errors
If lookup_info is provided but is not in a table:
Lookup information, if supplied, must be in a table.
Unable to retrieve logical subscriber information.
Unable to retrieve extended wallet info for logical subscriber.
Unable to get subscriber wallet information.
Usage
This function is used by many other NCC API functions, particularly periodic charge management, to serve as a function-level cache for subscriber, wallet, and service information in order to prevent multiple lookups across operations.
local l = ccs.wallet.fill_lookup_info ()
-- perhaps modify information here
local wu = { BALANCES = { ['147'] = 1000 } }
ccs.wallet.extended_update (wu, l)
▲ ccs.wallet.get_balance (wallet, balance_id)
Parameters
wallet
A wallet structure, as returned by ccs.wallet.info or ccs.wallet.extended_info.
balance_id
The ID of the balance structure to return.
Returns
Either nil if the balance_id cannot be found in the wallet, or a single balance type table in this format:
{
ID = <balance ID>
-- other balance fields
BUCKETS (if present in wallet information) = {
<bucket ID> = {
ID = <bucket ID>
-- other bucket fields
}
}
Errors
None.
Usage
This function serves as a shortcut accessor to select balance types from wallet information returned by ccs.wallet.info or ccs.wallet.extended_info. It returns the balance structure requested or nil if the balance does not exist in the wallet information provided.
local extendedWalletInfo = ccs.wallet.extended_info ()
local balance = ccs.wallet.get_balance (extendedWalletInfo, pc.BALANCE_TYPE_ID)
local bucket = nil
if (balance) then
for id, b in pairs (balance) do
if (type (b) == 'table') then
bucket = b
break
end
end
end
▲ ccs.wallet.get_bucket (balance, balance_id)
Parameters
balance
A balance structure, as returned by ccs.wallet.get_balance.
bucket_id
The ID of the balance structure to return.
Returns
Either nil if the bucket_id cannot be found in the balance, or a single bucket table in this format:
{
ID = <bucket ID>
-- other bucket fields
}
Errors
None.
Usage
This function serves as a shortcut accessor to select buckets from balance types returned by ccs.wallet.extended_info (ccs.wallet.info does not return buckets). It returns the bucket structure requested or nil if the bucket does not exist in the balance information provided.
local extendedWalletInfo = ccs.wallet.extended_info ()
local balance = ccs.wallet.get_balance (extendedWalletInfo, pc.BALANCE_TYPE_ID)
local bucket = ccs.wallet.get_bucket (balance, 123)