Profile Tags
Profile Operations
The N2 Logic Node’s API exposes all profile tags in any profile block for reading and writing.
Profile Blocks
Profile blocks are referred to via the ncc.profile data structure, e.g.
-- using the outgoing profile block as an example
ncc.profile.block.<block name> -- e.g. ncc.profile.block.OUTGOING
ncc.profile.block["<block name>"] -- e.g. ncc.profile.block["OUTGOING"]
<block number> -- e.g. 20
"<block name>" -- e.g. "OUTGOING"
It is important to know the profile tag type of the profile tag in ACS in order to use the appropriate method type when reading or writing values, as it will affect the interpretation of the values within your Lua script.
Profile Tags
Profile tags are referenced as straight integers, identical to their definition in ACS. These values can be retrieved and queried using NCC platform data functions.
Reading Profile Values
Read Method Parameters
All read methods take identical parameters:
- block - the profile block (mandatory)
- tag - the profile tag (mandatory)
Read Method Errors
All read methods can raise the following errors:
If the block parameter is not valid:
Profile block is not a valid profile block identifier.
Profile block <block> is not a valid profile block identifier.
If the tag parameter cannot be parsed to a number:
Profile tag must be of type number, not <tag type>.
If the returned value is not parseable into bytes:
Retrieved profile value is not a string.
Read Functions
Additionally, if the bytes returned do not match an unsigned short or unsigned long length (i.e. are not 1, 2, or 4): As noted above, an ACS integer field with no value will equate to an integer field of 0.
▲ ncc.profile.read_int (block, tag)
Parameters
As for Read method parameters.
Returns
The value stored at the profile block and tag as an integer. Note that the NCC SDK does not distinguish between an integer value of 0 and no value stored in an integer profile!
Errors
As for Read method errors.
Need 4, 2, or 1 byte(s) for uint, have <bytes length>.
Usage
Use this function to read a value from an integer profile field, e.g.:
if (ncc.profile.read_int ("TEMPORARY", 100) == 1) then
-- etc.
▲ ncc.profile.read_str (block, tag)
Parameters
As for Read method parameters.
Returns
The value stored at the profile block and tag as a string.
Errors
As for Read method errors.
Usage
Use this function to read a value from a string profile field, e.g.:
x = ncc.profile.read_str ("OUTGOING", 101)
if (x == "") then
-- value not present
else
ncc.debug ("Found " .. x)
end
▲ ncc.profile.read_nstr (block, tag)
Parameters
As for Read method parameters.
Returns
The value stored at the profile block and tag as a numeric string.
Errors
As for Read method errors.
Usage
Use this function to read a value from a numeric string profile field, e.g.:
subscriber = {}
subscriber.CLI = ncc.profile.read_nstr ("INCOMING", 327683)
The table returned will be in a format of PREFIX => VALUE pairs, e.g. The value of each pair depends on the prefix tree’s type and configuration within ACS - refer to the ncc.profile.write_ptree function.
▲ ncc.profile.read_ptree (block, tag)
Parameters
As for Read method parameters.
Returns
The value stored at the profile block and tag as a Lua table.
Errors
As for Read method errors. Additionally, refer to the possible errors returned by the n2 Library ncc.logic.ptree.decode function.
Usage
Use this function to read a value from a prefix tree profile field, e.g.:
x = ncc.profile.read_ptree("CCS_GLOBAL_CONFIG", 10)
if (x == "") then
-- value not present
else
ncc.debug ("CCS barred/allowed list is:")
ncc.debug (x)
end
{
["1122"] = 0,
["1234"] = 0,
["2345"] = 0
}
Writing Profile Values
Write Method Parameters
All write methods take identical parameters:
- block - the profile block (mandatory)
- tag - the profile tag (mandatory)
- value - the value to write to the block and tag (mandatory)
Note that the NCC SDK does not support deletion of profile tag values. Nil strings can be written, however.
Write Method Errors
If the block parameter is not valid:
Profile block is not a valid profile block identifier.
Profile block <block> is not a valid profile block identifier.
If the tag parameter cannot be parsed to a number:
Profile tag must be of type number, not <tag type>.
Write Functions
▲ ncc.profile.write_int (block, tag, value)
Parameters
As for Write method parameters.
Returns
Nothing.
Errors
As for Write method errors.
Usage
Use this function to write a value to an integer profile field, e.g.:
y = 100
ncc.profile.write_int ("TEMPORARY", y, y)
▲ ncc.profile.write_str (block, tag, value)
Parameters
As for Write method parameters.
Returns
Nothing.
Errors
As for Write method errors.
Usage
Use this function to write a value from a string profile field, e.g.:
ncc.alarm.error ("Problem with call ID "
.. ncc.engine.field.call_id ()
.. " to " .. ncc.engine.field.called_party_id ().DIGITS
.. "; recording NOA to outgoing channel.")
ncc.profile.write_str ("OUTGOING", 1312003, ncc.engine.called_party_id ().NOA)
▲ ncc.profile.write_nstr (block, tag, value)
Parameters
As for Write method parameters.
Returns
Nothing.
Errors
As for Write method errors.
Usage
Use this function to write a value to a numeric string profile field, e.g.:
-- write caller location number to extension digits 0
ncc.profile.write_nstr ("INCOMING", 327693, ncc.engine.field.location_num ())
Important considerations There are two additional points to know when writing prefix tree values to ACS:
▲ ncc.profile.write_ptree (block, tag, value)
Parameters
As for Write method parameters.
Returns
Nothing.
Errors
As for Write method errors.
Usage
Use this function to write a value to a prefix tree profile field, e.g.:
local ba_list = {
['1122'] = 0,
['1234'] = 0,
['5566'] = 0,
['4321'] = 0,
['5678'] = 0,
['8765'] = 0
}
ncc.profile.write_ptree ("TEMPORARY", 100, ba_list)
Other Functions
▲ ncc.profile.is_hex_str (target)
Parameters
target
The value to check (mandatory).
Returns
True if target can be cast to a numeric string, false otherwise.
Errors
None.
Usage
NCC numeric string fields are limited to only having hexadecimal characters. This function allows you to confirm that the target string is valid for use in a numeric string field.
x = "ABC123"
if (ncc.profile.is_hex_str (x)) then
-- true