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"
}
}
}
}
}
Functions
- ccs.named_event.direct
- ccs.named_event.reserve
- ccs.named_event.confirm
- ccs.named_event.revoke
- ccs.named_event.successful
If no named event class is supplied: If no named event name is supplied: If minimum units is specified but is not able to be turned into a number: If maximum units is specified but is not able to be turned into a number: If the ignore balance limits indicator is specified but is neither true nor false: If discount percentage is specified but is not able to be turned into a number: If the named event status is not able to be turned into a number: If the named event status is not recognised as a valid named event status code:
▲ ccs.named_event.direct (named_event_info)
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.
Named event class must be supplied.
Named event name must be supplied.
Minimum units must be a number, if supplied.
Maximum units must be a number, if supplied.
Ignore balance limits indicator must be true or false, if supplied.
Discount percentage must be a number, if supplied.
Named event status is not readable.
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
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.
▲ ccs.named_event.reserve (named_event_info)
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.
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
If used units is specified but is not able to be turned into a number: If the named event status is not parseable: If the named event status is not able to be turned into a number: If the named event status is not recognised as a valid named event status code: 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.
▲ ccs.named_event.confirm (named_event_info)
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.
Used units must be a number, if supplied.
Named event status is not readable.
Unable to determine named event status.
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.
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
If the named event status is not parseable: If the named event status is not able to be turned into a number: If the named event status is not recognised as a valid named event status code: 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.
▲ ccs.named_event.revoke (named_event_info)
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.
Named event status is not readable.
Unable to determine named event status.
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.
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
▲ ccs.named_event.successful (result)
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