Call

This Activity is used to represent a call, e.g., from a phone or an intercom station.

Props

Note: If the Activity was triggered by a Dial Operation, the value of the DialNum property must exactly match the Dial Operation parameter. Otherwise it may not be possible to correlate a specific Call Activity with a previous Dial Operation.

Member

A valid Call Activity has at least one member, at most one of which can be the source. Usually, there is exactly one source and one destination for telephony calls. For Intercom calls there may be more than one destination (group call).

Roles

• Source - Typically the caller.
• Destination - Typically the callee(s).

Props

Possible values for the State Property are:

• For role Source:
  • 0: Default (i.e. no member-specific state)
  • 7: OnHold (Used when this member currently holds the call.)
• For role Destination:
  This state should only be set to anything but ‘default’ if the member state differs from the overall call state.
  • 0: Default (i.e. no member-specific state)
  • 1: Signaling ≥ext.adapter 0.1.11 (Used when the call is signaled for this member)
  • 3: Busy ≥ext.adapter 0.1.11 (Used when this member is busy or has declined the call)
  • 4: Fault ≥ext.adapter 0.1.11
  • 7: OnHold (Used when this member currently holds the call)

App Semantics of Member States

The exact interpretation of state values of the Call Activity and its members is application-specific. Though when determining the overall state of a call from a local user’s point of view, the following behaviour can be generally expected:

• If the Activity member that corresponds to the user’s local device has a state, this state communicated to the user.
  • If this member state is invalid (i.e. a value that is not listed above for the role which is currently assigned to that member), it is ignored.
• If the local member has no valid state attached to it, the application may fall back to the Activity state.
• If no state can be determined (i.e. neither the local member nor the Activity has a valid state), the application may default to any valid state or alternatively ignore the Activity until its state is updated to a valid value.
• For some member state values, this behavior may be overridden and the remote member’s state is selected as the deciding factor. This is typically only the case when the local member doesn’t have a state, i.e. the local member’s state usually takes precedence over anything else.

Operations

Accept

Operation to accept a call.

HangUp

Operation to hang up a call.

Hold

Operation to hold a call. The state of a member holding the call is set to OnHold.

Intended for phone calls.

Resume

Operation to resume a previously held call. As result the state of all members should be set to Default again.

Intended for phone calls.

BlindTransfer

Operation to transfer a participant to another number. The member sending the BlindTransfer Operation is not part of the resulting call.

Intended for phone calls.

Transfer

Operation to transfer a participant to a known participant of another call. The member sending the Transfer Operation is not part of the resulting call.

Intended for phone calls.

Conference

Operation to start a conference with all given calls.

Intended for phone calls.

SplitConference

Operation to split a running conference in single calls. Each call should be connected to calling source.

Intended for phone calls.

Park

Operation to park a call to a given park position. The source should not be part of the call when it is parked.

Intended for phone calls.

Take

Operation to take the parked call. The Operation is called on a parked Activity. The calling source will be the source of the taken call.

Intended for phone calls.

Key

Operation to send a key on the call.

Module XML example

Intercom

<Objects>
    <!-- Intercom -->
    <Object id="Intercom" exclude="1">
        <!-- Intercom.Device -->
        <Object id="Device" name="[obj.intercom]">
            <Property id="Number" type="int" address="1" minval="1" />
            <Operation id="OpenDoor" />

            <Activity id="mycall" role="Source, Destination" />
        </Object>
    </Object>
</Objects>

<Activities>
    <!-- Intercom call -->
    <Activity id="mycall" type="Call">
        <Property id="CallType" type="int">
            <Option id="None" value="0" />
            <Option id="Normal" value="1" />
            <Option id="Emergency" value="2" />
        </Property>
        <Property id="StartTime" type="time" />
        <Property id="DialNum" type="string" optional="1" />
        <State id="State" type="int" >
            <Option id="Invalid" value="0" />
            <Option id="Signaling" value="1" />
            <Option id="Connected" value="2" />
            <Option id="Busy " value="3" />
            <Option id="Fault" value="4" />
        </State>

        <ObjectRole id="ObjectRoleBase" exclude="1">
            <State id="State" type="int">
                <Option id="Default" value="0" />
                <Option id="Signaling" value="1" />
                <Option id="Busy " value="3" />
                <Option id="Fault" value="4" />
                <Option id="OnHold" value="7" />
            </State>
            <Property id="Num" type="string" optional="1" />
        </ObjectRole>

        <ObjectRole id="Source" extends="ObjectRoleBase" />
        <ObjectRole id="Destination" extends="ObjectRoleBase" multiple="1" />

        <Operation id="Accept">
            <Property id="@member" type="string" />
        </Operation>
        <Operation id="HangUp">
            <Property id="@member" type="string" />
        </Operation>
    </Activity>
</Activities>

Telephony

<Objects>
    <!-- Telephony -->
    <Object id="Telephony" exclude="1">
        <!-- Telephony.Phone -->
        <Object id="Phone">
            <Property id="Number" type="int" address="1" minval="1" />

            <Activity id="phoneCall" role="Source, Destination" />
        </Object>
    </Object>
</Objects>

<Activities>
    <!-- Phone call -->
    <Activity id="phoneCall" type="Call">
        <Property id="CallType" type="int">
            <Option id="None" value="0" />
            <Option id="Normal" value="1" />
            <Option id="Emergency" value="2" />
        </Property>
        <Property id="StartTime" type="time" />
        <Property id="DialNum" type="string" optional="1" />
        <Property id="State" type="int">
            <Option id="Invalid" value="0" />
            <Option id="Signaling" value="1" />
            <Option id="Connected" value="2" />
            <Option id="Busy " value="3" />
            <Option id="Fault" value="4" />
        </Property>

        <ObjectRole id="ObjectRoleBase" exclude="1">
            <State id="State" type="int">
                <Option id="Default" value="0" />
                <Option id="OnHold" value="7" />
            </State>
            <Property id="Num" type="string" optional="1" />
        </ObjectRole>

        <ObjectRole id="Source" extends="ObjectRoleBase" />
        <ObjectRole id="Destination" extends="ObjectRoleBase" multiple="1" />

        <Operation id="Accept">
            <Property id="@member" type="string" />
        </Operation>
        <Operation id="HangUp">
            <Property id="@member" type="string" />
        </Operation>
        <Operation id="Hold">
            <Property id="@member" type="string" />
        </Operation>
        <Operation id="Resume">
            <Property id="@member" type="string" />
        </Operation>
        <Operation id="BlindTransfer">
            <Property id="@member" type="string" />
            <Property id="@targetNumber" type="string" />
        </Operation>
        <Operation id="Transfer">
            <Property id="@member" type="string" optional="1" />
            <Property id="@otherCall" type="string" />
        </Operation>
        <Operation id="Conference">
            <Property id="@member" type="string" />
            <Property id="@otherCalls" type="string[]" />
        </Operation>
        <Operation id="SplitConference">
            <Property id="@member" type="string" optional="1" />
        </Operation>
        <Operation id="Park">
            <Property id="@member" type="string" />
            <Property id="@pos" type="string" />
        </Operation>
        <Operation id="Take">
            <Property id="@member" type="string" />
        </Operation>
        <Operation id="Key">
            <Property id="@member" type="string" />
            <Property id="@key" type="string" />
        </Operation>
    </Activity>
</Activities>

App XML example

Intercom

<Activities>
    <!-- Intercom call -->
    <Activity id="mycall" type="Call">
        <ObjectRole id="ObjectRoleBase">
            <App>
                <Mapping>
                    <State id="State" value="1" appstate="Message" appevent="Message" appevent_text="[activity.call.normal]" condition="activity.CallType==1" />
                    <State id="State" value="1" appstate="Alarm" appevent="Alarm" appevent_text="[activity.call.emergency]" condition="activity.CallType==2" />
                    <State id="State" value="2" appstate="Active" />
                </Mapping>
            </App>
        </ObjectRole>
    </Activity>
</Activities>

Telephony

<Activities>
    <!-- Telephony call -->
    <Activity id="mycall" type="call">
    <ObjectRole id="Source">
        <App>
            <Mapping>
                <Generic id="mycheck" condition="(activity.State == 1 or activity.State == 2) and num=12345" appevent="Alarm" appurl="datapoint[aaaaaaaa-bbbb-cccc-dddd-eeeeeeee]"/>
            </Mapping>
        </App>
    </ObjectRole>
</Activity>
</Activities>

Workflow

The call Activity is started and ended by the device adapter - either directly or upon request by the application. All changes in the device adapter - i.e. creating/destroying or updating an Activity - are synchronized to the application. Note: When a call ends, the Activity should be ended directly - removing all members before ending the Activity should be avoided.

Note that the call Activity does not use the activity.Start/activity.End API functions to request starting or ending a call on behalf of the application. Instead, it sends Connect (Intercom Functionality), Dial or Call (both Phone Functionality) Operations for starting, and the HangUp (Call Activity or either Functionality, depending on which is defined) Operation for ending the call.

Specific to Telephony

For a telephony Activity to be properly displayed in the application, it must contain the following members (it will be mapped properly either way though):

• One member which is either the local phone device or a parking position - both of which need to be configured in the application Settings.
• One other member which is neither the local phone device nor a parking position (referred to as the remote member).

An Activity with the state “connected” needs to have exactly two participants.

The Operations of the Activity mostly overlap with those of the phone Functionality. The Operations available for the Object via the Functionality take priority over those in the call Activity (i.e. if an Operation is available for both the local telephone Object and the Activity, the application will prefer the Object Operation).

Calls with more than two participants

Telephony Activities cannot have more than two members. Telephone conferences are made up of multiple Call Activities that are linked together at the application level.

Intercom Activities cannot be linked together as application-level conferences. An intercom group call is repesented as a single Call Activity with more than one destination member.

Changing participants of an existing call

Members of an existing call Activity shall not be changed. Instead, the call Activity should end and a new call Activity with the updated member list should be created. This applies to all use cases where participants are exchanged including, but not limited to:

• When parking/unparking the call. Here, a participant is replaced with a park position (or vice-versa).
• When a call is transferred/forwarded.

Setting the StartTime

The StartTime property of the Activity can be used to display the current call’s duration to the end user and therefore should be set according to end user expectation, i.e. mimic the behavior of the physical telephony device. In general, this means setting the StartTime to the current time when the combination of Activity members changes, e.g. after a transfer or park Operation. For example, when a call is taken out of a park position, this is the beginning of a conversation from the user’s point of view and a physical phone on the user’s desk would likely start counting the call duration from zero in this situation. Therefore, the StartTime should be set to the current time regardless of the call start time reported by the underlying telephony system which could be a time point even before the call was put in a park position in the first place. Similarly, the time should be reset when a call is being parked.

Error

If the connection could not be established, for example because the target is busy, the Activity is set into the respective state. Depending on the Extension the Activity can be ended or stays open until the user ends it through the HangUp Operation.