Asterisk cmd SetGroup

Synopsis

SetGroup(groupname[@category])

Description

Sets the channel group to the specified value. Equivalent to SetVar(GROUP=group).
Use categories to sort specifc groupnames into super-groups, which is equivalent to SetVar(GROUP_category=group). Each channel = call leg can have its own group.

Also note the existence of the special variable $OUTBOUND_GROUP: that group will be assigned to the channels created by the dial() app. There is also OUTBOUND_GROUP_ONCE which is unset after use. Both OUTBOUND_GROUP and OUTBOUND_GROUP_ONCE supports group@category (for exampe OUTBOUND_GROUP=mygroup@mycategory)

This command is deprecated in Asterisk v1.2. Instead use

GROUP([category])=groupname
Set(GROUP()=test)

Details

One of the major recent additions to Asterisk is app_groupcount, that you can use to limit the number of calls to, well, just about anything. A SIP peer, a PRI link, a call center staff member, a conference and calls to or from your boy and/or girlfriend

The command for setting a group is setgroup(), the command for enforcing a limitation in Asterisk 1.0.x is checkgroup().
For Asterisk 1.2.x CheckGroup() has been deprecated, instead use a combination of the GotoIf application and the GROUP_COUNT() function.

Please start using this instead of the incominglimit and outgoinglimit settings in sip.conf. Outgoinglimit is not working as expected and the more general solution with app_groupcount is a much better solution that works cross channels. This is an end-of-life warning for outgoinglimit - but note that incominglimit will stay!

Bug in Asterisk 1.0.x

According to bug 3067 transferred calls are not correctly managed by Asterisk 1.0.x with regard to the GROUP variable, so be aware!

Introduced with Asterisk 1.1 branch

See bug 2529
  1. adds GetGroupMatchCount, which accepts a regex for group name and returns total count of all matching groups found
  2. adds "group show channels" to the CLI, which lists all active channels that have groups assigned; also accepts a regex, which is matched against the group names

Example 1


exten => 999,1,SetGroup(moh) ;Set Current Group to moh
exten => 999,2,CheckGroup(1) ;Check moh does not have more than 1
exten => 999,3,Answer ;Answer the call
exten => 999,4,MusicOnHold(default) ;Play default Music on hold
exten => 999,103,Busy ;Play busy if 1 person is already listening

Example 2 (not correct? Read below!)

Problem: How to limit incoming calls to SIP channels using the SetGroup & Checkgroup command. I don't want any call waiting on SIP channels!
Approach: One solution is to increment the GROUPCOUNT for both the caller and callee, to ensure the callee doesn't get a 2nd call while on the phone.

[sip-phones]

; increment GROUPCOUNT for the calling exten
exten => 200,1,SetGroup(${CALLERIDNUM})

; increment GROUPCOUNT for exten you are calling
exten => 200,2,SetGroup(${EXTEN})

; ensure this is the 1st call to this exten
exten => 200,3,CheckGroup(1)

; dial if we make it this far
exten => 200,4,Dial(200)

; CheckGroup jumped here, 200 is on the phone
exten => 200,104,Busy


You will also want to ensure you SetGroup(${CALLERIDNUM}) before dialing any outgoing numbers as well (to PSTN,etc). ie:

[outbound-local]
exten => _9NXXXXXX,1,SetGroup(${CALLERIDNUM})
...


Example 2 Revised.

After braking my head on the above code (it just didn't work) I'm revising it (I'm not the author of the first one).
The problem with the above code is that setgroup is only incremented once per channel, and each channel can only be associated to one group (it's just a variable that is part of a channel), so if I do a setgroup(foo), then when I do setgroup(bar) group foo is reset to 0 (provided foo was 0 before). The workaround is to use setvar(OUTBOUND_GROUP=foo), this will set the called channel into it's own group (foo).

Alternatives: Instead you might want to look into the Local channel construct with /n in order to create yet another call leg for the same call that then can have another GROUP variable assigned to it. Or use the new @categories.

So here we go:
Problem: How to limit incoming calls to SIP channels using the SetGroup & Checkgroup command. I don't want any call waiting on SIP channels!
Approach: One solution is to increment the GROUPCOUNT for both the caller and callee, to ensure the callee doesn't get a 2nd call while on the phone.

[sip-phones]

; increment GROUPCOUNT for exten you are calling
exten => 200,1,SetGroup(${EXTEN})

; now check if the count is more than 1
exten => 200,2,CheckGroup(1)

; well if you got this far then the group count is <= 1, and one is from the calling channel,
; since this channel has only one leg
; now we can go ahead and set the group for our leg of the call, so that nobody can call us while we are on the phone.
exten => 200,3,SetGroup({CALLERIDNUM})
; now we set the group for the other leg of our call
exten => 200,4,SetVar(OUTBOUND_GROUP=${EXTEN})
; now dial
exten => 200,5,Dial(200)

; CheckGroup jumped here, 200 is on the phone
exten => 200,103,Busy


Simple update for Asterisk 1.4


; set the group for our leg of the call - called party, so that nobody call (before call setup)
exten => _20XX,1,Set(GROUP()=${EXTEN})
; check if the other person is on the phone
exten => _20XX,n,GotoIf($[${GROUP_COUNT(${EXTEN})}>1]?busy)
; set the group for our leg of the call - calling party, so that nobody can call us while we are on the phone
exten => _20XX,n,Set(GROUP()=${CALLERID(num)})
; set the group for the other leg of our call, so nobody can call them while we are on the phone
exten => _20XX,n,Set(OUTBOUND_GROUP=${EXTEN})
; dial the sip extension
exten => _20XX,n,Dial(SIP/${EXTEN})
; busy / hangup if extension already on call
exten => _20XX,n(busy),Hangup


You will also want to ensure you SetGroup(${CALLERIDNUM}) before dialing any outgoing numbers as well (to PSTN,etc). ie:

[outbound-local]
exten => _9NXXXXXX,1,SetGroup(${CALLERIDNUM})
...

There might also be a way to work around the above by using categories (example: setgroup(${CALLERIDNUM}@${CALLERIDNUM}), and setgroup(${EXTEN}@$EXTEN})) but I havn't tested it yet. Please update if you do. ==> See Example 6

Example 3


see the superdial macro page

Example 4 (Matt Riddell's Example)


The idea is that when you do setgroup you are putting this caller into a group. I.E. you could have

exten => s,1,SetGroup(People_With_Short_Hair)

That would put anyone who visits this extension into the People_With_Short_Hair group.
Then if you do:

exten => s,2,CheckGroup(678)

You can make sure that there are not more than 678 people already in the People_With_Short_Hair group.
If there are more than 678 people in the group then the application will go to the priority x+101 where x is the current priority.
See the ,2, on the checkgroup line? That's the current priority. So, 2+101=103.
So you could have a line

exten => s,103,Playback(more_than_678_short_hair)

which would only be played if there are more than 678 people in the group.
If however there are less than or equal to the number inside the brackets for checkgroup (say for example there are 500 people who have short hair), then it will continue to the next priority.

As above, the current priority is 2 when you do the checkgroup, so the next priority is 3. This means that you can have the line:

exten => s,3,Playback(less_than 678_short_hair)

Now, if we put them all together you'd end up with:

exten => s,1,SetGroup(People_With_Short_Hair)
exten => s,2,CheckGroup(678)
exten => s,3,Playback(less_than_or_equal_to_678_short_hair)
exten => s,103,Playback(more_than_678_short_hair)


Example 5 (Tagapache's Example) using the GROUP() function.


SetGroup and CheckGroup have been deprecated in (i think the rel I have is 1.0.7). I get
horribly confused with CVS Head and which release I have at any one point.

Instead you use the GROUP() function. Here is a working fragment from a SAIL-generated dial plan.
It works very well, choking the outbound calls at whatever number is set. This won't work on stable
releases, at least up to 1.0.9.

;********************************************************************
;
; S T D V O I P - with choke
;
;********************************************************************
[macro-stdvoip]
;
; ${ARG1} - full dial string
; Return ${DIALSTATUS} = CHANUNAVAIL if ${VOIPMAX} exceeded
;
;
exten => s,1,Set(GROUP()=OUTBOUND_GROUP) ;Set Group
exten => s,2,GotoIf($[${GROUP_COUNT()} > ${VOIPMAX}]?103) ;Exceeded?
exten => s,3,Dial(${ARG1}) ;dial it
exten => s,103,SetVar(DIALSTATUS=CHANUNAVAIL) ;deny call

${VOIPMAX} is a user-set Global which limits the concurrent number of outbound VOIP calls


Example 6 Using Categories in 1.0.x (Ramon's example)


Using categories you are able to set multiple groups on only one active channel.
So you are able to set the amount of calls on the called channel but also on the calling channel.

exten => 200,1,SetGroup(CW@${EXTEN})
; Increase the number of calls on the called channel
exten => 200,2,CheckGroup(1@CW)
; Check if called channel has more than 1 call
exten => 200,3,SetGroup(CW@${CALLERIDNUM})
; Increase the number of calls on the calling channel
exten => 200,4,Dial(SIP/200)
; Call the extension
exten => 200,103,Busy
; Checkgroup jumped here if there was more than 1 call.

Note that this works in Asterisk 1.0.7 and no longer in new releases, See Example 5 for more info...
Also Note that a problem in Asterisk 1.0.x will cause incorrect data on transfer of calls

Example 7 Using Categories in 1.2.x (Ramon's example)


Using categories you are able to set multiple groups on only one active channel.
So you are able to set the amount of calls on the called channel but also on the calling channel.

exten => 200,1,Set(GROUP(${EXTEN})=OUTBOUND_GROUP)
; Increase number of calls on the called channel
exten => 200,n,GotoIf($[${GROUP_COUNT(OUTBOUND_GROUP@${EXTEN})} > 1]?BLOCK)
; Check if called channel has more than 1 call.
exten => 200,n,Set(GROUP(${CALLERIDNUM})=OUTBOUND_GROUP)
; Increase number of calls on the calling channel
exten => 200,n,Dial(SIP/200)
; Call the extension
exten => 200,n(BLOCK),Busy
; GotoIf jumped here if the was more than 1 call using labels



See also



Go back to Asterisk - documentation of application commands

Synopsis

SetGroup(groupname[@category])

Description

Sets the channel group to the specified value. Equivalent to SetVar(GROUP=group).
Use categories to sort specifc groupnames into super-groups, which is equivalent to SetVar(GROUP_category=group). Each channel = call leg can have its own group.

Also note the existence of the special variable $OUTBOUND_GROUP: that group will be assigned to the channels created by the dial() app. There is also OUTBOUND_GROUP_ONCE which is unset after use. Both OUTBOUND_GROUP and OUTBOUND_GROUP_ONCE supports group@category (for exampe OUTBOUND_GROUP=mygroup@mycategory)

This command is deprecated in Asterisk v1.2. Instead use

GROUP([category])=groupname
Set(GROUP()=test)

Details

One of the major recent additions to Asterisk is app_groupcount, that you can use to limit the number of calls to, well, just about anything. A SIP peer, a PRI link, a call center staff member, a conference and calls to or from your boy and/or girlfriend

The command for setting a group is setgroup(), the command for enforcing a limitation in Asterisk 1.0.x is checkgroup().
For Asterisk 1.2.x CheckGroup() has been deprecated, instead use a combination of the GotoIf application and the GROUP_COUNT() function.

Please start using this instead of the incominglimit and outgoinglimit settings in sip.conf. Outgoinglimit is not working as expected and the more general solution with app_groupcount is a much better solution that works cross channels. This is an end-of-life warning for outgoinglimit - but note that incominglimit will stay!

Bug in Asterisk 1.0.x

According to bug 3067 transferred calls are not correctly managed by Asterisk 1.0.x with regard to the GROUP variable, so be aware!

Introduced with Asterisk 1.1 branch

See bug 2529
  1. adds GetGroupMatchCount, which accepts a regex for group name and returns total count of all matching groups found
  2. adds "group show channels" to the CLI, which lists all active channels that have groups assigned; also accepts a regex, which is matched against the group names

Example 1


exten => 999,1,SetGroup(moh) ;Set Current Group to moh
exten => 999,2,CheckGroup(1) ;Check moh does not have more than 1
exten => 999,3,Answer ;Answer the call
exten => 999,4,MusicOnHold(default) ;Play default Music on hold
exten => 999,103,Busy ;Play busy if 1 person is already listening

Example 2 (not correct? Read below!)

Problem: How to limit incoming calls to SIP channels using the SetGroup & Checkgroup command. I don't want any call waiting on SIP channels!
Approach: One solution is to increment the GROUPCOUNT for both the caller and callee, to ensure the callee doesn't get a 2nd call while on the phone.

[sip-phones]

; increment GROUPCOUNT for the calling exten
exten => 200,1,SetGroup(${CALLERIDNUM})

; increment GROUPCOUNT for exten you are calling
exten => 200,2,SetGroup(${EXTEN})

; ensure this is the 1st call to this exten
exten => 200,3,CheckGroup(1)

; dial if we make it this far
exten => 200,4,Dial(200)

; CheckGroup jumped here, 200 is on the phone
exten => 200,104,Busy


You will also want to ensure you SetGroup(${CALLERIDNUM}) before dialing any outgoing numbers as well (to PSTN,etc). ie:

[outbound-local]
exten => _9NXXXXXX,1,SetGroup(${CALLERIDNUM})
...


Example 2 Revised.

After braking my head on the above code (it just didn't work) I'm revising it (I'm not the author of the first one).
The problem with the above code is that setgroup is only incremented once per channel, and each channel can only be associated to one group (it's just a variable that is part of a channel), so if I do a setgroup(foo), then when I do setgroup(bar) group foo is reset to 0 (provided foo was 0 before). The workaround is to use setvar(OUTBOUND_GROUP=foo), this will set the called channel into it's own group (foo).

Alternatives: Instead you might want to look into the Local channel construct with /n in order to create yet another call leg for the same call that then can have another GROUP variable assigned to it. Or use the new @categories.

So here we go:
Problem: How to limit incoming calls to SIP channels using the SetGroup & Checkgroup command. I don't want any call waiting on SIP channels!
Approach: One solution is to increment the GROUPCOUNT for both the caller and callee, to ensure the callee doesn't get a 2nd call while on the phone.

[sip-phones]

; increment GROUPCOUNT for exten you are calling
exten => 200,1,SetGroup(${EXTEN})

; now check if the count is more than 1
exten => 200,2,CheckGroup(1)

; well if you got this far then the group count is <= 1, and one is from the calling channel,
; since this channel has only one leg
; now we can go ahead and set the group for our leg of the call, so that nobody can call us while we are on the phone.
exten => 200,3,SetGroup({CALLERIDNUM})
; now we set the group for the other leg of our call
exten => 200,4,SetVar(OUTBOUND_GROUP=${EXTEN})
; now dial
exten => 200,5,Dial(200)

; CheckGroup jumped here, 200 is on the phone
exten => 200,103,Busy


Simple update for Asterisk 1.4


; set the group for our leg of the call - called party, so that nobody call (before call setup)
exten => _20XX,1,Set(GROUP()=${EXTEN})
; check if the other person is on the phone
exten => _20XX,n,GotoIf($[${GROUP_COUNT(${EXTEN})}>1]?busy)
; set the group for our leg of the call - calling party, so that nobody can call us while we are on the phone
exten => _20XX,n,Set(GROUP()=${CALLERID(num)})
; set the group for the other leg of our call, so nobody can call them while we are on the phone
exten => _20XX,n,Set(OUTBOUND_GROUP=${EXTEN})
; dial the sip extension
exten => _20XX,n,Dial(SIP/${EXTEN})
; busy / hangup if extension already on call
exten => _20XX,n(busy),Hangup


You will also want to ensure you SetGroup(${CALLERIDNUM}) before dialing any outgoing numbers as well (to PSTN,etc). ie:

[outbound-local]
exten => _9NXXXXXX,1,SetGroup(${CALLERIDNUM})
...

There might also be a way to work around the above by using categories (example: setgroup(${CALLERIDNUM}@${CALLERIDNUM}), and setgroup(${EXTEN}@$EXTEN})) but I havn't tested it yet. Please update if you do. ==> See Example 6

Example 3


see the superdial macro page

Example 4 (Matt Riddell's Example)


The idea is that when you do setgroup you are putting this caller into a group. I.E. you could have

exten => s,1,SetGroup(People_With_Short_Hair)

That would put anyone who visits this extension into the People_With_Short_Hair group.
Then if you do:

exten => s,2,CheckGroup(678)

You can make sure that there are not more than 678 people already in the People_With_Short_Hair group.
If there are more than 678 people in the group then the application will go to the priority x+101 where x is the current priority.
See the ,2, on the checkgroup line? That's the current priority. So, 2+101=103.
So you could have a line

exten => s,103,Playback(more_than_678_short_hair)

which would only be played if there are more than 678 people in the group.
If however there are less than or equal to the number inside the brackets for checkgroup (say for example there are 500 people who have short hair), then it will continue to the next priority.

As above, the current priority is 2 when you do the checkgroup, so the next priority is 3. This means that you can have the line:

exten => s,3,Playback(less_than 678_short_hair)

Now, if we put them all together you'd end up with:

exten => s,1,SetGroup(People_With_Short_Hair)
exten => s,2,CheckGroup(678)
exten => s,3,Playback(less_than_or_equal_to_678_short_hair)
exten => s,103,Playback(more_than_678_short_hair)


Example 5 (Tagapache's Example) using the GROUP() function.


SetGroup and CheckGroup have been deprecated in (i think the rel I have is 1.0.7). I get
horribly confused with CVS Head and which release I have at any one point.

Instead you use the GROUP() function. Here is a working fragment from a SAIL-generated dial plan.
It works very well, choking the outbound calls at whatever number is set. This won't work on stable
releases, at least up to 1.0.9.

;********************************************************************
;
; S T D V O I P - with choke
;
;********************************************************************
[macro-stdvoip]
;
; ${ARG1} - full dial string
; Return ${DIALSTATUS} = CHANUNAVAIL if ${VOIPMAX} exceeded
;
;
exten => s,1,Set(GROUP()=OUTBOUND_GROUP) ;Set Group
exten => s,2,GotoIf($[${GROUP_COUNT()} > ${VOIPMAX}]?103) ;Exceeded?
exten => s,3,Dial(${ARG1}) ;dial it
exten => s,103,SetVar(DIALSTATUS=CHANUNAVAIL) ;deny call

${VOIPMAX} is a user-set Global which limits the concurrent number of outbound VOIP calls


Example 6 Using Categories in 1.0.x (Ramon's example)


Using categories you are able to set multiple groups on only one active channel.
So you are able to set the amount of calls on the called channel but also on the calling channel.

exten => 200,1,SetGroup(CW@${EXTEN})
; Increase the number of calls on the called channel
exten => 200,2,CheckGroup(1@CW)
; Check if called channel has more than 1 call
exten => 200,3,SetGroup(CW@${CALLERIDNUM})
; Increase the number of calls on the calling channel
exten => 200,4,Dial(SIP/200)
; Call the extension
exten => 200,103,Busy
; Checkgroup jumped here if there was more than 1 call.

Note that this works in Asterisk 1.0.7 and no longer in new releases, See Example 5 for more info...
Also Note that a problem in Asterisk 1.0.x will cause incorrect data on transfer of calls

Example 7 Using Categories in 1.2.x (Ramon's example)


Using categories you are able to set multiple groups on only one active channel.
So you are able to set the amount of calls on the called channel but also on the calling channel.

exten => 200,1,Set(GROUP(${EXTEN})=OUTBOUND_GROUP)
; Increase number of calls on the called channel
exten => 200,n,GotoIf($[${GROUP_COUNT(OUTBOUND_GROUP@${EXTEN})} > 1]?BLOCK)
; Check if called channel has more than 1 call.
exten => 200,n,Set(GROUP(${CALLERIDNUM})=OUTBOUND_GROUP)
; Increase number of calls on the calling channel
exten => 200,n,Dial(SIP/200)
; Call the extension
exten => 200,n(BLOCK),Busy
; GotoIf jumped here if the was more than 1 call using labels



See also



Go back to Asterisk - documentation of application commands

Created by: imcdona, Last modification: Mon 06 of Sep, 2010 (15:55 UTC) by JustRumours
Please update this page with new information, just login and click on the "Edit" or "Discussion" tab. Get a free login here: Register Thanks! - Find us on Google+