Skip to end of metadata
Go to start of metadata

Use Cases

Mailboxes/MWI

  1. App can create a custom mailbox
    1. Are mailboxes given names, or do they have unique id's?
      1. names
    2. Does a mailbox's existence persist across restarts? What about it's state?
      1. No persistence; Asterisk requests a refresh at restart/registration
  2. App can publish a new state for a mailbox
    1. Are there any common attributes for mailbox state (unplayed message count, last message timestamp, etc.)
      1. ast_mwi_state is defined as new message count, old message count

Presence

  1. App can create new presence state
    1. Apps are named
  2. App can publish new presence state
    1. Are there any common attributes for presence state (state, last change timestamp, etc.)

Device State

  1. App can create a custom device state
    1. This can be used as an extension state in the dialplan
  2. App can publish new device state
    1. Are there any common attributes for device state (state, last change timestamp, etc.)

Proposal one: Generic topics

API

GET /topics List[Topic] - list all topics, with optional filter for type

GET /topics/{topicId} Topic - get information about a specific topic

DELETE /topics/{topidId} - destroy a topic. This should implicitly unsubscribe all subscribers.

POST /topics Topic - create a new topic. When you create a topic, you are implicitly subscribed to that topic.

    type: The type of topic to create. Valid types initially would be 'mailbox', 'device', 'presence'

    uri: The URI subscribers will use to subscribe to the topic

POST /topics/{topicId}/publish - publish an event to a topic. Events are passed as JSON, and are opaque from the perspective of ARI. It would be up to the specific topic types to understand the  event packages.

 

/applications/{applicationName}/subscription will be updated to allow for an ARI client to subscribe to any topic in Asterisk.

Data model

Topic:

  •     type: string - Valid types initially would be 'mailbox', 'device', 'presence'
  •     uri: string - The URI subscribers use to subscribe to the topic
  •     subscribers: List[Subscriber] - A list of active subscriptions
  •     id: string - A unique ID for the topic

 

Subscriber

  •     id: string - A unique ID for the subscriber
  •     topic_id: string - The topic ID this subscription refers to
  •     endpoint: Endpoint - If available, the endpoint that subscribed to this Topic

 

TopicSubscriptionCreated : Event - Event raised when a new subscription is created for a topic

  •     subscriber : Subscriber
  •     topic: Topic

 

TopicSubscriptionDestroyed : Event - Event raised when a subscription is destroyed for a topic

  •     subscriber : Subscriber
  •     topic : Topic

 

TopicEvent : Event - Event raised in relation to a topic

  •     topic : Topic
  •     body : JSON

 

TopicCreated : Event - Event raised when a new topic is created

  •     topic : Topic

 

TopicDestroyed : Event - Event raised when a topic is destroyed

  •     topic : Topic

Proposal two: First class resources

API

MethodURLReturn typeDescription
GET/mailboxes/{mailboxName}MailboxReturns the current state of a mailbox
PUT/mailboxes/{mailboxName}voidChanges the state of a mailbox
DELETE/mailboxes/{mailboxName}voidRemoves a mailbox controlled by ARI
GET/presence-states/{presenceName}PresenceReturns the current state of a Presence
PUT/presence-states/{presenceName}voidChanges presence state
DELETE/presence-states/{presenceName}voidRemoves a presence state controlled by ARI
GET/device-states/{deviceName}DeviceStateReturns the current state of a device
PUT/device-states/{deviceName}voidChanges the state of a device
DELETE/device-states/{deviceName}voidRemoves a device state controlled by ARI
  • Because names can include : or /, be sure to urlencode them.
  • PUT is appropriate, since status updates are idempotent, and these objects are explicitly named
  • You can only PUT or DELETE /presence-state for CustomPresence:
  • You can only PUT or DELETE /device-state for Custom:
  • If you PUT or DELETE /mailboxes when app_voicemail or app_minivm is in use, the results are undefined
  • /applications/{applicationName}/subscription will be updated to handle mailbox:, presence:, and device: URI's
    • The implementation should be generalized so that handlers for URI schemes can be pluggable

Data Model

Mailbox

  • name: string
  • new_messages: int
  • old_message: int

DeviceState

  • name: string
  • state: string {}

PresenceState

  • name: string
  • state: string

Events

MailboxStateChanged

  • mailbox: Mailbox

DeviceStateChanged

  • device_state: DeviceState

PresenceStateChanged

  • presence_state: PresenceState

MailboxUpdateRequested - This is an odd event. When Asterisk starts, it has no mailbox state from the external application. This event requests that the external voicemail application PUT the current mailbox state back into Asterisk.

  • mailbox_name: string
  • No labels

2 Comments

  1. Use Cases

    Mailboxes/MWI

    1. App can create a custom mailbox
      1. Are mailboxes given names, or do they have unique id's?
        Mailboxes have unique IDs that are - essentially - their names. The naming scheme is mailbox@context, where context is just another identifier that provides a way to group mailboxes together. From the perspective of a SIP phone or something else that subscribes to mailbox state, it subscribes to this identifier.
      2. Does a mailbox's existence persist across restarts? What about it's state?
        No. A restart blows it out of Stasis cache. The VoiceMail provider API (provided in app.h) allows consumers of mailbox state to query a voicemail provider for the current state when that state is not in the cache. From the perspective of a phone, the MWI should not change if Asterisk is restarted. Thus, ARI will also have to be a voicemail provider. In practice, however, the only time when this occurs is on initial system start up - and so long as you receive a notification that someone wants the current state of the mailbox and you send it to them, this should work just fine.
    2. App can associate custom mailbox with a blinky light on a device
      1. Does this happen via the app, or via configuration?
        This is done by the phones, not the app. The app can't associate a mailbox with a device. The app can only provide state for the mailbox that a device wants. 
    3. App can publish a new state for a mailbox
      1. Are there any common attributes for mailbox state (unplayed message count, last message timestamp, etc.)
        It's all device specific. In practice, it is a new message count/old message count. Theoretically, however, you could want the state of any portion of someone' s mailbox, i.e., any folder message count. You could also want to differentiate between message priorities (normal, urgent, priority, etc.)

    Presence

    1. App can publish new presence state
      1. Are there any common attributes for presence state (state, last change timestamp, etc.)
        Presence State is only the state. State values, however, can be arbitrary.

    Device State

    1. App can create a custom device state
      1. This can be used as an extension state in the dialplan
        Correct, if someone put it in as an extension state. In fact, at some level, it has to be in the dialplan: if there isn't a hint for it in the dialplan, no one (device wise) can subscribe to it. That does make ARI have to have a level of dialplan integration that is unfortunate.
    2. App can publish new device state
      1. Are there any common attributes for device state (state, last change timestamp, etc.)
        It's ultimately device specific. When a device subscribes for the state of something, it states how it wants to receive the events. The tricky part becomes when what it subscribes for is ultimately a very device specific concept (such as the SNOM DIALOG_INFO_XML stuff.) The fact that these things exist - and someone may want to be able to create event bodies for them through ARI - is part of what leads to having a very generic event publish API.

    Proposal one: Generic topics

    API

    GET /topics List[Topic] - list all topics, with optional filter for type

    GET /topics/{topicId} Topic - get information about a specific topic

    DELETE /topics/{topidId} - destroy a topic. This should implicitly unsubscribe all subscribers.

    POST /topics Topic - create a new topic. When you create a topic, you are implicitly subscribed to that topic.

        type: The type of topic to create. Valid types initially would be 'mailbox', 'device', 'presence'

        uri: The URI subscribers will use to subscribe to the topic

    POST /topics/{topicId}/publish - publish an event to a topic. Events are passed as JSON, and are opaque from the perspective of ARI. It would be up to the specific topic types to understand the  event packages.

     

    /applications/{applicationName}/subscription will be updated to allow for an ARI client to subscribe to any topic in Asterisk.

    Data model

    Topic:

    •     type: string - Valid types initially would be 'mailbox', 'device', 'presence'
    •     uri: string - The URI subscribers use to subscribe to the topic
    •     subscribers: List[Subscriber] - A list of active subscriptions
    •     id: string - A unique ID for the topic

     

    Subscriber

    •     id: string - A unique ID for the subscriber
    •     topic_id: string - The topic ID this subscription refers to
    •     endpoint: Endpoint - If available, the endpoint that subscribed to this Topic

     

    TopicSubscriptionCreated : Event - Event raised when a new subscription is created for a topic

    •     subscriber : Subscriber
    •     topic: Topic

     

    TopicSubscriptionDestroyed : Event - Event raised when a subscription is destroyed for a topic

    •     subscriber : Subscriber
    •     topic : Topic

     

    TopicEvent : Event - Event raised in relation to a topic

    •     topic : Topic
    •     body : JSON

     

    TopicCreated : Event - Event raised when a new topic is created

    •     topic : Topic

     

    TopicDestroyed : Event - Event raised when a topic is destroyed

    •     topic : Topic

    Proposal two: First class resources

    Icon

    Work in progress...

    API

    /mailboxes/...

    /devicestates/...

    /presencestates/...

    Data Model

    Mailbox

    • id: string
    • custom: object - custom mailbox state

    DeviceState

    • id: string
    • custom: object - custom device state

    PresenceState

    • id: string
    • custom: object - custom presence state

    Events

    Mailbox{Created,Changed,Destroyed}

    • mailbox: Mailbox

    DeviceState{Created,Changed,Destroyed}

    • device_state: DeviceState

    PresenceState{Created,Changed,Destroyed}

    • presence_state: PresenceState

    I don't have any comments or problems with this approach. Since the actual 'state' is custom and is not provided by the API, it is proving my point that these concepts all end up being fundamentally identical in terms of their attributes, events, and general usage. I think the operations upon them will end up being very similar as well.

    1. (to bring our office discussion to the web) The key difference is that the content of the messages will be different. Even though the MWI notifications that Asterisk sends out will vary depending on the phone they are talking with, there will need to be code in Asterisk that can convert the incoming JSON into some sort of outgoing SIP message. Similarly for presence and device state.

      Since code has to be in Asterisk for handling the conversion for different phones, the API can reflect the implementation and document what it expects the fields to be. They may be similar in nature, but are fundamentally different in content.