☰
Navigation :

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:

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

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

Additionally, if the profile does not contain a supported byte count for an integer:

Need 8, 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.

As noted above, an ACS integer field with no value will equate to an integer field of 0.
▲ 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)
▲ 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

The table returned will be in a format of PREFIX => VALUE pairs, e.g.

{ 
    ["1122"] = 0,
    ["1234"] = 0,
    ["2345"] = 0
}

The value of each pair depends on the prefix tree’s type and configuration within ACS - refer to the ncc.profile.write_ptree function.

Writing Profile Values

Write Method Parameters

All write methods take identical parameters:

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.

Additionally, if the value is outside the range of values that can be stored in a profile:

Profile value <value> is too large for an integer profile.

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 ())
▲ 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)

Important considerations

There are two additional points to know when writing prefix tree values to ACS:

Prefix tree ordering: In most cases of writing prefix trees, the value selected for each pair is arbitrary and can be used at runtime for implementation-specific purposes. However, when writing to an Ordered Prefix Tree or Limited Ordered Prefix Tree, the values must* range from 0 to the total entries in the tree, i.e. 0..n. If this is not done, the tree may be unreadable for control plan nodes or the NCC GUI.

  • Limited prefix trees: When writing a Limited Prefix Tree or a Limited Ordered Prefix Tree, you will also need to write a second tree to a different profile block if you wish to actually set or use the limitations - refer to the ACS Technical Guide.

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