= Devices and Users =
 
  Note, this document might be a little dated.  It is the design spec for AMP 1.10.009, and the actual implementation may be a bit different.  Please update this document if your find differences.

1. Devices.  Each device has a unique account number that is not related to any user (ie: 00000001).

1.1 device.php stores device config (via sql) and writes device config (sip.conf, iax.conf, other - via retrieve script). For example:

{{{
[00000001]
username=00000001
mailbox=00000001@device   ; note, this a phony voicemail box
callerid="device" <00000001>
context=from-internal
< + other details >

or... (zapata.conf):

signalling=fxo_ks
mailbox=00000002@device
callerid="device" <00000002>
context=from-internal
channel=2
< + other details >
}}}

1.2) Devices can be logged in to, or fixed to an user. device.php adds keys to the "DEVICE" family in astdb.  The values include: the string to dial for that device, whether the device is fixed or adhoc (allows users to log in), and the fixed or default adhoc user mapping.

{{{
  (sip):

  dbput DEVICE 00000001/dial SIP/00000001
  dbput DEVICE 00000001/type [ fixed | adhoc ]
  dbput DEVICE 00000001/user 201  (this could be either the fixed user, or default adhoc user)

  (zapata):

  DEVICE/00000002/dial = zap/3

  the device key could also contain a non sip/iax/zap device:

  DEVICE/00000003/dial = SCCP/whatever
}}}


2) Users.  Users and Extensions are synonymous, and can be any unique number:

2.1) users.php collects information about users and their preferences.  Ultimately, users would be able to change their options in real-time, so we store the details in astdb.  *** does anyone have concerns about db1 scalability in asterisk??

{{{
  dbput  AMPUSER 201/cidname Ryan Courtnage
  dbput  AMPUSER 201/password 1234
  dbput  AMPUSER 201/ringtimer 15
  dbput  AMPUSER 201/noanswer [ just-ring | vmbox-1234 | ivr_3 | user-202 | etc... ]
}}}

2.2) users.php will also be responsible for creating extensions in the 
dialplan:

{{{
  exten => 201,1,Macro(dial,201)
}}}

2.3) To determine how an incoming call to a user should progress, dialplan macros (ie: macro-dial) will pull the astdb values for the callee.  For example, it will lookup the callee (the dialed number) in the AMPUSER family and retrieve the callee's ringtimer setting, and the noanswer setting.


3) Mapping Users to Devices.  A device can have a single user mapped to it.  A user can be mapped to multiple devices.

3.1) A user logs into a phone by using a service code (*xx)

3.2) The login application will dbget the 'type' for the device (fixed or adhoc) from the DEVICE family

3.3) If the device type is 'adhoc', the user will be prompted for user number and password.

3.4) After successful login, the device is mapped to the user, and the user is mapped to the device:

{{{
  dbput DEVICE ${DEVICEID}/user ${USERNUMBER}
  dbput AMPUSER ${USERNUMBER}/device ${DEVICEID}  (if this is already set to a device, then we append the new deviceid)
}}}

3.5) Incoming calls to a user (ie: 201) will dial the appropriate devices based on the device setting in the AMPUSER famiily.

4) Voicemail.  All devices are configured to use a unique "dummy" mailbox.  Users can optionally have a real mailbox.  When a user is mapped to a device, we will also link the dummy device mailbox to the user's real mailbox.  I've tested this "on the fly" linking to ensure MWI updates on phones - it does.

4.1) Device will have dummy mailbox set (see step 1): mailbox=00000001@device

4.2) When a user is mapped to a device, a symlink will be created from voicemail/device to voicemail/<uservmbox>

{{{
  ln -s /var/spool/asterisk/voicemail/default/201/ /var/spool/asterisk/voicemail/device/00000001
}}}

4.3) This symlink will be deleted if/when the user "logs off" the phone.

5) CallerID.  When a user originates a call, the dialplan will also need to determine & set the proper CallerID of the calling user.

5.1) AMP will enforce a strict rule for setting callerid in device configurations: calleridnum MUST be <deviceid> (ie: callerid="device" <00000001>).  This is important, since the ${CHANNEL} cannot be relied upon (ie: zap/3).

5.2) Before initiating Dial, the dialplan will perform a dbget from the DEVICE family based on the device's ${CALLERIDNUM} to obtain the user-number currently mapped to it 

5.3) A second dbget in the AMPUSER family (based on the result from 5.2) will grab the appropriate CIDNAME.

5.4) SetCallerID( ${CIDNAME} <${user-number}> ), then continue to dial.

See also:
DeviceUserPersitentStore