☰
Navigation :

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

*ccs.subscriber_for_cli

Wallet Data

Wallet Updates

Utility Functions

▲ 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.

If the cli provided is not a numeric string:

Subscriber CLI must be a numeric string.

If the response from the node is not parseable:

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.

The primary and secondary wallet information fields are only returned if the subscriber has wallets of that type.

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 forccs.subscriber_for_cli.
  Errors As forccs.subscriber_for_cli.
Usage This is a shorthand version of that queries for the current logical subscriber. 
local sub = ccs.subscriber ()
if (s.secondary) then
    -- logical subscriber has secondary wallet
end
▲ 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.

If the retrieved wallet information is not parseable:

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
▲ 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.

If the cli provided is not a numeric string:

Subscriber CLI must be a numeric string.

If the active domain has insufficient capabilities for the alternateWalletDetails action:

Insufficient capabilities for 'alternateWalletDetails' action.

If the retrieved wallet information is not parseable:

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
▲ 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.

If the retrieved wallet information is not parseable:

Retrieved wallet info is not readable.

If no base wallet information is returned from the node:

No base wallet info returned.

If no wallet balance information is returned from the node:

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
▲ ccs.wallet.extended_info ()
  Parameters None.  
  Returns Either nil if no wallet was returned, or a table of wallet information, formatted as perccs..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.

If the retrieved wallet information is not parseable:

Retrieved wallet info is not readable.

If no base wallet information is returned from the node:

No base wallet info returned.

If no wallet balance information is returned from the node:

No wallet balance info returned.

If no wallet bucket information is returned from the node:

No wallet bucket info returned.

If bucket information is found for a balance type that is not in the balance information:

Bucket information found for missing balance type <balance type>.

If bucket information for a balance type is not parseable:

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
▲ ccs.wallet.update (wallet)
  Parameters wallet A (limited) table of values, similar to the return value ofccs..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>
}

At least one of the first three fields must be set.

Unexpected values in the table will be ignored, so the results of accs..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.

  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.

If no wallet update information is provided:

Table of values must be provided for wallet update.

If there is no state, last access, and activation date information in the wallet table:

At least one value must be changed for a wallet update.

If the wallet update status returned from the thread is not readable:

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
▲ ccs.wallet.extended_update (wallet, lookup_info)
  Parameters wallet A (limited) table of values, similar to the return value ofccs.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>
}

At least one of the first three fields must be set.

Unexpected values in the table will be ignored, so the results of accs..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.
    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.

If no subscriber information can be retrieved:

Unable to retrieve logical subscriber information.

If no wallet update information is provided:

Table of values must be provided for wallet update.

If there is no state, start date, or balances in the wallet table:

At least one value must be changed for a wallet update.

If the wallet table has balances that are not in a table:

If provided, wallet balances must be a table for a wallet update.

If any balance type has a non-numeric balance type ID:

Invalid balance ID <balance type ID> provided for wallet update.

If any balance value has a non-numeric value:

Invalid balance value <balance type value> provided for wallet update.

If the wallet update status returned from the thread is not readable:

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

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.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.

If subscriber information cannot be retrieved for the logical subscriber:

Unable to retrieve logical subscriber information.

If no extended wallet information can be retrieved for the logical subscriber:

Unable to retrieve extended wallet info for logical subscriber.

If no wallet information can be retrieved for the 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.

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.

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 byccs..wallet.info orccs.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 byccs..wallet.info orccs.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)