Alpaca CLI 5.3

DataTypes

The datatypes that are found in the BroadWorks OCI schema map in a 1-to-1 fashion to those found in the AlpacaLibrary. For every XML type there is a corresponding type that can be found within the library. For example, in OCISchemaDataTypes.xsd you can find the 'AccessDeviceKey' datatype.

<xs:complexType name="AccessDeviceKey">
<xs:annotation>
  <xs:documentation>
    Key to uniquely identify a system, service provider, or group device.
  </xs:documentation>
</xs:annotation>
<xs:sequence>
  <xs:element name="serviceProviderId" type="ServiceProviderId" minOccurs="0"/>
  <xs:element name="groupId" type="GroupId" minOccurs="0"/>
  <xs:element name="deviceName" type="AccessDeviceName"/>
</xs:sequence>
</xs:complexType>

The Alpaca Generator reads this datatype and outputs it as a Java class.

/**
 * Key to uniquely identify a system, service provider, or group device.
 */
public class AccessDeviceKey implements Serializable {

    @Size(min = 1, max = 30)
    protected String serviceProviderId;

    @Size(min = 1, max = 30)
    protected String groupId;

    @NotNull
    @Size(min = 1, max = 40)
    protected String deviceName;
...

The XML datatypes are converted in the following Java types that can be found in the AlpacaLibrary:

  • BroadWorksObjects
  • Requests
  • Responses
  • Enumerations
  • Tables
  • Generic Datatypes (effectively POJOs)

BroadWorksObjects

BroadWorksObjects are a datatype that is not found within the OCI schema. However, they are implied by the naming of the schema documents. For example, a 'User' has an OCI schema document but there is no defined datatype in the schema to determine what is a 'User'. In Alpaca we have mapped a specific request to each BroadWorksObject and those fields have determined what the first class type contains.

For example, in BroadWorks R20 the UserGetRequest20 has been mapped to the User class. You can create a User object and populate its fields by calling User u = User.getPopulatedUser(broadWorksServer, "userId"); The User object will contain methods to retrieve all the information available within a UserGetResponse20 as well as some additional methods for ease of use.

The available first class BroadWorksObjects are:

  • User
  • Group
  • ServiceProvider
  • Enterprise
  • GroupAccessDevice
  • ServiceProviderAccessDevice
  • SystemAccessDevice
  • AutoAttendant
  • BroadWorksAnywherePortal
  • CallCenter
  • CollaborateBridge
  • FindMeFollowMe
  • FlexibleSeatingHost
  • GroupPaging
  • InstantGroupCall
  • MeetMeConferencingBridge
  • RoutePoint
  • VoiceXml

Objects can be created without calling the underlying Request to retrieve their fields from the BroadWorks system. In this state they are considered 'unpopulated'. You can check if an object is populated by calling the .hasPopulated() method. An unpopulated BroadWorksObject can be populated by calling the .populate() method.

Requests

Requests are the instrument by which you can perform changes and retrieve information from the BroadWorks server. A request will have a minimum of one parameter. There are often additional values that can be set on the request before calling the .fire() method and receiving a response. Requests can also be fired in asynchronous ways which will be covered later.

Requests typically fall into the following types:

  • Get
  • Modify
  • Add
  • Delete
  • Assign
  • Authorize

If you wanted to retrieve the list of services assigned to a given user you would begin by creating your request object.

UserServiceGetAssignmentListRequest request = new UserServiceGetAssignmentListRequest(user);

This request can then call .fire() to retrieve the BroadWorks response.

UserServiceGetAssignmentListResponse response = request.fire();

Since this request does not have any additional parameters, this sequence can be shortened to a single line.

UserServiceGetAssignmentListResponse response = new UserServiceGetAssignmentListRequest(user).fire();

Requests can perform validation prior to being fired by enabling it in the Alpaca configuration. If this is enabled, JSR303 bean validation is used to check that the Request matches the validation as described in the OCI XML documentation.

Responses

Response objects are returned from the .fire() method of any Request. They contain the information as returned by BroadWorks. In modification Requests such as 'Add' and 'Modify' the Response type is typically the container object DefaultResponse. This container can be interrogated by .isErrorResponse() to determine if the action was successful. If an error occured additional information can be read through .getSummaryText() and .getDetailText(). These both correspond to specific XML elements and their usage varies as determined by BroadSoft.

Most Get Requests will return a custom Response type with methods to call the type of information that is returned. Following the Request example from above, we can retrieve the table of service assignments.

UserServiceGetAssignmentListResponse response = new UserServiceGetAssignmentListRequest(user).fire();
if(response.isErrorResponse()) {
    // Do Something
}
List<UserServiceServicePacksAssignmentTableRow> serviceTable = response.getServicePacksAssignmentTable();

Responses will contain methods to retrieve each of the fields and datatypes that can be accessed from the response.

Enumerations

BroadWorks OCI enumerations are simply Java typed enumerations that are designed to have the OCI required string mapped to the Java enumeration value.

For example, the UserService datatype is an enumeration with all available User services. Passing the 'Call Me Now' service as a parameter would be UserService.CALLMENOW which would be output in XML as <service>Call Me Now</service>.

Tables

Tables are not defined programmatically in the schema. They are currently described in the documentation of a given Request. However, in Alpaca we have defined all of the OCI tables by their rows. Due to the lack of programmatic description within the OCI schema we are currently unable to determine the datatype of the values in each row. Each value is simply evaluated as a String with the parsing of the values left up to the developer.

for(UserServiceServicePacksAssignmentTableRow row : response.getServicePacksAssignmentTable()) {
    String servicePackName = row.getServicePackName();
    String description = row.getDescription();
}

Generic Datatype

Generic datatypes are both returned from Responses and required as parameters in Requests. When received in a Response the datatype fields can simply be retrieved for use from the available getters. When used in a Request the type should be created as new {Object} and the available setters used to populate the data. Parameters that are required in the datatype per the schema will be included in the constructor. 

AccessDeviceEndpointAdd endpointAdd = new AccessDeviceEndpointAdd(accessDevice, linePort);
endpointAdd.setPortNumber(5);

UserSharedCallAppearanceAddEndpointRequest scaAddRequest = 
      new UserSharedCallAppearanceAddEndpointRequest(user,
                                                      endpointAdd,
                                                      isActive,
                                                      allowOrigination,
                                                      allowTermination);