Navigation :

Named Events

Named Event Functions

Overview

The NCC Charging API allows you to reserve, confirm, revoke, or directly charge named events to a billing domain.

All named event operations are for the current logical subscriber only.

Named Event Status

The result of named event requests made through the Logic Node are returned as enumerated values. These can be directly accessed for their value or their text equivalent.

Direct Named Event Statuses

ccs = {
    named_event = {
        status = {
            direct = {
                value = {
                    ["SUCCESS"] = 0,
                    ["INSUFFICIENT_FUNDS"] = 1,
                    ["NOT_ALLOWED"] = 2,
                    ["COMMS_ERROR"] = 3,
                    ["SYSTEM_ERROR"] = 4,
                    ["NO_RESERVATION"] = 5
                },
                text = {
                    [0] = "success",
                    [1] = "insufficient funds",
                    [2] = "not allowed",
                    [3] = "communications error",
                    [4] = "system error",
                    [5] = "no reservation placed"
                }
            }
        }
    }
}

Note that the ‘no reservation’ code for direct named events is included for completeness only, as it is defined in the NCC API. This code is not expected to occur and should be considered a system error.

Reserve Named Event Statuses

ccs = {
    named_event = {
        status = {
            reserve = {
                value = {
                    ["SUCCESS"] = 0,
                    ["INSUFFICIENT_FUNDS"] = 1,
                    ["MAX_CONCURRENT"] = 2,
                    ["NOT_ALLOWED"] = 3,
                    ["COMMS_ERROR"] = 4,
                    ["SYSTEM_ERROR"] = 5,
                    ["INVALID_STATE"] = 6
                },
                text = {
                    [0] = "success",
                    [1] = "insufficient funds",
                    [2] = "maximum concurrent accesses exceeded",
                    [3] = "not allowed",
                    [4] = "communications error",
                    [5] = "system error",
                    [6] = "invalid wallet state"
                }
            }
        }
    }
}

Confirm Named Event Statuses

ccs = {
    named_event = {
        status = {
            confirm = {
                value = {
                    ["SUCCESS"] = 0,
                    ["INSUFFICIENT_FUNDS"] = 1,
                    ["NOT_ALLOWED"] = 2,
                    ["COMMS_ERROR"] = 3,
                    ["SYSTEM_ERROR"] = 4,
                    ["NO_RESERVATION"] = 5
                },
                text = {
                    [0] = "success",
                    [1] = "insufficient funds",
                    [2] = "not allowed",
                    [3] = "communications error",
                    [4] = "system error",
                    [5] = "no reservation placed"
                }
            }
        }
    }
}

Revoke Named Event Statuses

ccs = {
    named_event = {
        status = {
            revoke = {
                value = {
                    ["SUCCESS"] = 0,
                    ["FAILED"] = 1,
                    ["NO_RESERVATION"] = 2
                },
                text = {
                    [0] = "success",
                    [1] = "failed",
                    [2] = "no reservation placed"
                }
            }
        }
    }
}


Parameters	named_event_info	A table of named event information for the operation, formatted as: { EVENT_CLASS = "<named event class>" -- string as specified in the NCC GUI, mandatory (limit: (200 characters) EVENT_NAME = "<named event name>" -- string as specified in the NCC GUI, mandatory (limit: 20 characters) MINIMUM_UNITS = <minimum units required> -- integer, optional (default: 1) MAXIMUM_UNITS = <maximum units required> -- integer, optional (default: 1) IGNORE_BALANCE_LIMITS = <true\|false> -- boolean, optional (default: false) DISCOUNT_PERCENTAGE = <discount percentage> -- integer, optional (default: 0) -- note that for cash charges this should be specified with the system currency's -- base, e.g. an 80% discount using a base 100 currency would be 8000 and a 50% -- discount using a base 10000 currency would be 500000. EXTRA_INFORMATION = "<additional EDR information>" -- TAG=VALUE, pipe-separated string, optional (default: null, limit: 600 characters) CALLER_TIMEZONE = "<timezone of the caller>" -- string in Unix timezone format, optional (default: null, limit: 32 characters) }
Returns	A direct named event status code.
Errors	If named event information is not supplied in a table: `Named event information must be supplied in a table.` If no named event class is supplied: `Named event class must be supplied.` If no named event name is supplied: `Named event name must be supplied.` If minimum units is specified but is not able to be turned into a number: `Minimum units must be a number, if supplied.` If maximum units is specified but is not able to be turned into a number: `Maximum units must be a number, if supplied.` If the ignore balance limits indicator is specified but is neither true nor false: `Ignore balance limits indicator must be true or false, if supplied.` If discount percentage is specified but is not able to be turned into a number: `Discount percentage must be a number, if supplied.` If the named event status is not able to be turned into a number: `Named event status is not readable.` If the named event status is not recognised as a valid named event status code: `Unrecognised named event status code <status code> returned.`
Usage	Use this function to send a direct (i.e. no reserve/confirm) named event request to the active billing domain. The information provided in named_event_info will depend on the configuration of the named event you are requesting. `local r = ccs.named_event.direct ({ EVENT_CLASS = "Test Events", EVENT_NAME = "Test Event" }) if (r == ccs.named_event.status.direct.value.SUCCESS) then -- direct charge made successfully for logical subscriber else ncc.debug ("Direct named event failed due to " .. ccs.named_event.status.direct.text[r]) end`


Parameters	named_event_info	As for ccs.named_event.direct.
Returns	A reserve named event status code.
Errors	As for ccs.named_event.direct.
Usage	Use this function to send a named event reservation request to the active billing domain. The information provided in named_event_info will depend on the configuration of the named event you are requesting. Only one reservation can be active at a time during an NCC interaction. This can apply even across multiple instances of the Logic Node, so is not enforced. If the reservation is successful but not confirmed or revoked then it will remain on the subscriber’s account, and the billing engine will be responsible for closing it when stale. `local r = ccs.named_event.reserve ({ EVENT_CLASS = "Test Events", EVENT_NAME = "Test Event" }) if (r == ccs.named_event.status.reserve.value.SUCCESS) then -- reservation is open for logical subscriber else ncc.debug ("Named event reservation failed due to " .. ccs.named_event.status.reserve.text[r]) end`


Parameters	named_event_info	A table of named event information for the operation, formatted as: `{ USED_UNITS = <used units> -- integer, optional (default: 1) EXTRA_INFORMATION = "<additional EDR information>" -- TAG=VALUE, pipe-separated string, optional (default: null, limit: 600 characters) } For convenience, this parameter can be omitted if you wish to use default values.`
Returns	A confirm named event status code.
Errors	If named event information is supplied, but not in a table: `Named event information must be supplied in a table.` If used units is specified but is not able to be turned into a number: `Used units must be a number, if supplied.` If the named event status is not parseable: `Named event status is not readable.` If the named event status is not able to be turned into a number: `Unable to determine named event status.` If the named event status is not recognised as a valid named event status code: `Unrecognised named event status code <status code> returned.`
Usage	Use this function to confirm a previously-sent named event reservation on the active billing domain. As reservation confirmation may occur across multiple instances of the Logic Node in a single control plan, no checking is done to ensure a previous reservation has occurred. local ne = { EVENT_CLASS = "Test Events", EVENT_NAME = "Test Event", EXTRA_INFORMATION = "TYPE=test\|CODE=123" } local r = ccs.named_event.reserve (ne) if (r == ccs.named_event.status.reserve.value.SUCCESS) then -- processing for reservation successful r = ccs.named_event.confirm (ne) -- re-use for same EXTRA_INFORMATION if (r == ccs.named_event.status.confirm.value.SUCCESS) then -- charge successful, carry on with processing else ncc.debug ("Named event confirmation failed due to " .. ccs.named_event.status.confirm.text[r]) end end


Parameters	named_event_info	A table of named event information for the operation, formatted as: `{ EXTRA_INFORMATION = "<additional EDR information>" -- TAG=VALUE, pipe-separated string, optional (default: null, limit: 600 characters) } For convenience, this parameter can be omitted if you wish to use default values.`
Returns	A revoke named event status code.
Errors	If named event information is supplied, but not in a table: `Named event information must be supplied in a table.` If the named event status is not parseable: `Named event status is not readable.` If the named event status is not able to be turned into a number: `Unable to determine named event status.` If the named event status is not recognised as a valid named event status code: `Unrecognised named event status code <status code> returned.`
Usage	Use this function to revoke a previously-sent named event reservation on the active billing domain. As reservation revocation may occur across multiple instances of the Logic Node in a single control plan, no checking is done to ensure a previous reservation has occurred. `local r = ccs.named_event.reserve ({ EVENT_CLASS = "Test Events", EVENT_NAME = "Test Event" }) if (r == ccs.named_event.status.reserve.value.SUCCESS) then -- processing for reservation successful r = ccs.named_event.revoke () if (r == ccs.named_event.status.revoke.value.SUCCESS) then -- revoke successful, carry on with processing else ncc.debug ("Named event revoke failed due to " .. ccs.named_event.status.revoke.text[r]) end end`


Parameters	result	The result value from a previous ccs.named_event.direct, ccs.named_event.reserve, ccs.named_event.confirm, or ccs.named_event.revoke function call.
Returns	true if the named event operation was successful, otherwise false.
Errors	None.
Usage	This is a shortcut function to check the provided result against the four “successful” named event statuses. `local e = { EVENT_CLASS = "Test Events", EVENT_NAME = "Test Event" } local r = ccs.named_event.reserve (e) if (ccs.named_event.successful (r)) then -- processing for reserve success if (ccs.named_event.successful (ccs.named_event.confirm ())) then -- processing for confirm success else -- processing for confirm failure end else -- processing for reserve failure end`