Merged revisions 57364 via svnmerge from
[asterisk/asterisk.git] / doc / sla.txt
1 -------------------------------------------------------------------------------
2 --- Shared Line Appearances ---------------------------------------------------
3 -------------------------------------------------------------------------------
4
5 -------------------------------------------------------------------------------
6 INTRODUCTION
7
8 The "SLA" functionality in Asterisk is intended to allow a setup that emulates
9 a simple key system.  It uses the various abstraction layers already built into
10 Asterisk to emulate key system functionality across various devices, including
11 IP channels.
12 -------------------------------------------------------------------------------
13
14 -------------------------------------------------------------------------------
15 DIALPLAN CONFIGURATION
16
17 The SLA implementation can automatically generate the dialplan necessary for
18 basic operation if the "autocontext" option is set for trunks and stations in
19 sla.conf.  However, for reference, here is an automatically generated dialplan
20 to help with custom building of the dialplan to include other features, such as
21 voicemail.
22
23 However, note that there is a little bit of additional configuration needed if
24 the trunk is an IP channel.  This is discussed in the TRUNKS section.
25
26 [line1]
27 exten => s,1,SLATrunk(line1)
28
29 [line2]
30 exten => s,2,SLATrunk(line2)
31
32 [sla_stations]
33 exten => station1,1,SLAStation(station1)
34 exten => station1_line1,hint,SLA:station1_line1
35 exten => station1_line1,1,SLAStation(station1_line1)
36 exten => station1_line2,hint,SLA:station1_line2
37 exten => station1_line2,1,SLAStation(station1_line2)
38
39 exten => station2,1,SLAStation(station2)
40 exten => station2_line1,hint,SLA:station2_line1
41 exten => station2_line1,1,SLAStation(station2_line1)
42 exten => station2_line2,hint,SLA:station2_line2
43 exten => station2_line2,1,SLAStation(station2_line2)
44
45 exten => station3,1,SLAStation(station3)
46 exten => station3_line1,hint,SLA:station3_line1
47 exten => station3_line1,1,SLAStation(station3_line1)
48 exten => station3_line2,hint,SLA:station3_line2
49 exten => station3_line2,1,SLAStation(station3_line2)
50 -------------------------------------------------------------------------------
51
52 -------------------------------------------------------------------------------
53 TRUNKS
54
55 Be sure to configure the trunk's context to be the same one that is set for the
56 "autocontext" option in sla.conf if automatic dialplan configuration is used.
57 This would be done in the regular device entry in zapata.conf, sip.conf, etc.
58 Note that the automatic dialplan generation creates the SLATrunk() extension
59 at extension 's'.  This is perfect for Zap channels that are FXO trunks, for
60 example.  However, it may not be good enough for an IP trunk, since the call
61 coming in over the trunk may specify an actual number.
62
63 If the dialplan is being built manually, ensure that calls coming in on a trunk
64 execute the SLATrunk() application with an argument of the trunk name, as shown
65 in the dialplan example before.
66
67 IP trunks can be used, but they require some additional configuration to work.
68
69 For this example, let's say we have a SIP trunk called "mytrunk" that is going
70 to be used as line4.  Furthermore, when calls come in on this trunk, they are
71 going to say that they are calling the number "12564286000".  Also, let's say
72 that the numbers that are valid for calling out this trunk are NANP numbers,
73 of the form _1NXXNXXXXXX.
74
75 In sip.conf,  there would be an entry for [mytrunk].  For [mytrunk], 
76 set context=line4.
77
78
79 sla.conf:
80
81 [line4]
82 type=trunk
83 device=Local/disa@line4_outbound
84
85
86 extensions.conf:
87
88 [line4]
89 exten => 12564286000,1,SLATrunk(line4)
90
91 [line4_outbound]
92 exten => disa,1,Disa(no-password|line4_outbound)
93 exten => _1NXXNXXXXXX,1,Dial(SIP/${EXTEN}@mytrunk)
94
95
96 So, when a station picks up their phone and connects to line 4, they are
97 connected to the local dialplan.  The Disa application plays dialtone to the
98 phone and collects digits until it matches an extension.  In this case, once
99 the phone dials a number like 12565551212, the call will proceed out the
100 SIP trunk.
101 -------------------------------------------------------------------------------
102
103
104 -------------------------------------------------------------------------------
105 STATIONS
106
107 Currently, the only channel driver that has all of the features necessary to
108 support an SLA environment is chan_sip.  Here are some hints on configuring
109 a SIP phone for use with SLA:
110
111 1) Add the SIP channel as a [station] in sla.conf.
112
113 2) Configure the phone in sip.conf.  If automatic dialplan configuration was
114    used by enabling the "autocontext" option in sla.conf, then this entry in
115    sip.conf should have the same context setting.
116
117 3) On the phone itself, there are various things that must be configured to
118    make everything work correctly:
119
120    Let's say this phone is called "station1" in sla.conf, and it uses trunks
121    named "line1" and line2".
122
123    a) Two line buttons must be configured to subscribe to the state of the
124       following extensions:
125         - station1_line1
126         - station1_line2
127
128    b) The line appearance buttons should be configured to dial the extensions
129       that they are subscribed to when they are pressed.
130
131    c) If you would like the phone to automatically connect to a trunk when it
132       is taken off hook, then the phone should be automatically configured to
133       dial "station1" when it is taken off hook.
134 -------------------------------------------------------------------------------
135
136
137 -------------------------------------------------------------------------------
138 VOICEMAIL
139
140 This is an example of how you could set up a single voicemail box for the
141 phone system.  The voicemail box number used in this example is 1234, which
142 would be configured in voicemail.conf.
143
144 For this example, assume that there are 2 trunks and 3 stations.  The trunks
145 are Zap/1 and Zap/2.  The stations are SIP/station1, SIP/station2, and
146 SIP/station3.
147
148 In zapata.conf, channel 1 has context=line1 and channel 2 has context=line2.
149
150 In sip.conf, all three stations are configured with context=sla_stations.
151
152 When the stations pick up their phones to dial, they are allowed to dial
153 NANP numbers for outbound calls, or 8500 for checking voicemail.
154
155
156 sla.conf:
157
158 [line1]
159 type=trunk
160 device=Local/disa@line1_outbound
161
162 [line2]
163 type=trunk
164 device=Local/disa@line2_outbound
165
166 [station](!)
167 type=station
168 trunk=line1
169 trunk=line2
170
171 [station1](station)
172 device=SIP/station1
173
174 [station2](station)
175 device=SIP/station2
176
177 [station3](station)
178 device=SIP/station3
179
180
181 extensions.conf:
182
183 [macro-slaline]
184 exten => s,1,SLATrunk(${ARG1})
185 exten => s,n,Goto(s-${SLATRUNK_STATUS}|1)
186 exten => s-FAILURE,1,Voicemail(1234|u)
187 exten => s-UNANSWERED,1,Voicemail(1234|u)
188
189 [line1]
190 exten => s,1,Macro(slaline|line1)
191
192 [line2]
193 exten => s,2,Macro(slaline|line2)
194
195 [line1_outbound]
196 exten => disa,1,Disa(no-password|line1_outbound)
197 exten => _1NXXNXXXXXX,1,Dial(Zap/1/${EXTEN})
198 exten => 8500,1,VoicemailMain(1234)
199
200 [line2_outbound]
201 exten => disa,1,Disa(no-password|line2_outbound)
202 exten => _1NXXNXXXXXX,1,Dial(Zap/2/${EXTEN})
203 exten => 8500,1,VoicemailMain(1234)
204
205 [sla_stations]
206
207 exten => station1,1,SLAStation(station1)
208 exten => station1_line1,hint,SLA:station1_line1
209 exten => station1_line1,1,SLAStation(station1_line1)
210 exten => station1_line2,hint,SLA:station1_line2
211 exten => station1_line2,1,SLAStation(station1_line2)
212
213 exten => station2,1,SLAStation(station2)
214 exten => station2_line1,hint,SLA:station2_line1
215 exten => station2_line1,1,SLAStation(station2_line1)
216 exten => station2_line2,hint,SLA:station2_line2
217 exten => station2_line2,1,SLAStation(station2_line2)
218
219 exten => station3,1,SLAStation(station3)
220 exten => station3_line1,hint,SLA:station3_line1
221 exten => station3_line1,1,SLAStation(station3_line1)
222 exten => station3_line2,hint,SLA:station3_line2
223 exten => station3_line2,1,SLAStation(station3_line2)
224
225 -------------------------------------------------------------------------------