Alpaca 6.6

Warning! You are viewing an older version of Alpaca Guides. View the latest

Developer Guide

The Alpaca Developer guide introduces concepts and principles for extending Alpaca to better meet the custom needs of Service Providers.

Setup

Spring

Spring framework is an open source Java platform that provides comprehensive infrastructure support for developing robust Java applications very easily and very rapidly.

See the Spring documentation for help and tutorials.

Getting Started

Alpaca can be extended through plugins and library scripts. Plugins can be either Provisioning or Transform related and are better explained later in the document. Extending Alpaca almost always requires connecting to BroadWorks.

Connecting to BroadWorks

The starting point for any Alpaca Library application is the BroadWorksServer object. Creating a BroadWorksServer will perform the login procedure and verify that the server matches the expected platform version.

Provisioning Plugin


    @ProvisioningComponent(priority = 5, description = "My Provisioning Plugin", name = "ProvisioningPlugin")
    @Component
    public class PhoneNumberProvisioningListener implements PreUserAddListener {
        
        @Autowired
        BroadWorksConnectionService broadWorksConnectionService;
        
        @Override
        public void preUserAdd(TaskDTO task, UserProvisioningDTO provisioningUserDTO) throws ProvisioningException {
            
            // Retrieve BroadWorks Server
            BroadWorksServer broadWorksServer = broadWorksConnectionService.getConnection("myClusterName");
            
            // Perform Provisioning Task
    
        }
    }

Transform Plugin



@TransformComponent(priority = 15)
@Component
public class MyBroadWorksClusterTransform> implements ServiceProviderMigrationTransform {

    @Override
    public T transform(BroadWorksProcess process, BroadWorksServer destination, T information, boolean isAdoptDestinationDefaultDomain, String newId) {
        // Retrieve BroadWorks Server
        BroadWorksServer broadWorksServer = process.getBroadWorksServer();
        
        // Perform Transform
        ...
        
        return information;
    }
}

Library Script



@Component
public class MyAlpacaClass {
    
    @Autowired
    BroadWorksConnectionService broadWorksConnectionService;
    
    public MyAlpacaClass() {
        // Constructor
    }
    
    public void myMethod() {
        
        // Retrieve BroadWorksServer
        BroadWorksServer broadWorksServer = broadWorksConnectionService.getConnection("myClusterName");
        
        // Perform Requests w/ BroadWorksServer
    }
}

Alpaca Properties

All Alpaca Properties located in the application-prod.yml can be accessed via the AlpacaProperties class.



@Component
public class MyAlpacaClass {
    
    @Autowired
    AlpacaProperties alpacaProperties;
    
    public MyAlpacaClass() {
        // Constructor
    }
    
    public void myMethod() {
        
        // Retrieve auditLog.retentionDays property
       int retentionDays = alpacaProperties.getAuditLogs().getRetentionDays();
       
       // Do something with retrieved property
    }
}

Firing Requests

All OCI Requests have a corresponding Java class that can be created. To get all the Access Devices in a BroadWorks system you would need to send a SystemAccessDeviceGetAllRequest. In Alpaca this would be accomplished by calling:



SystemAccessDeviceGetAllRequest accessDeviceGetAllRequest = new SystemAccessDeviceGetAllRequest(broadWorksServer);

All required fields for the request will be in the constructor. However, many OCI request have optional fields that can be accessed by calling .setX(Y) on the Request object prior to sending it to BroadWorks.

After the Request has been created it can be sent to the system by calling .fire(). For GET type requests they will return a specific Response.



SystemAccessDeviceGetAllResponse accessDeviceGetAllResponse = accessDeviceGetAllRequest.fire();

Requests can also be fired asynchronously by calling .asyncFire() and passing in the function to call on completion.


accessDeviceGetAllRequest.asyncFire(response -> {
    response.getAccessDeviceTable();
});

Request Per Object Producer

The Request Per Object Producer performs a Request across a list of BroadWorksObjects. The Request Per Object Producer lives in the RequestHelper class.



public List retrieveBLFUriForUsers(BroadWorksServer broadWorksServer, List users) {
    
    // Create list for uris
    List userBLFUriList = new ArrayList<>();
    
    try {
        // Call requestPerObjectProducer
        RequestHelper.requestPerObjectProducer(
                // Pass in BroadWorks Server
                broadWorksServer,
                // Pass in List of Users
                users,
                // Type of item in the list
                User.class,
                // Request to perform
                UserBusyLampField.UserBusyLampFieldGetRequest.class,
                // Consumer
                (user, response) -> {
                   if(!response.isErrorResponse() && response.getListURI() != null) {
                         userBLFUriList.add(response.getListURI());                      
                   }
                },
                // Expected Error Codes - This particular error code is "Service not assigned"
                 "4410");
    } catch (RequestException ex) {
        log.error("Error while retrieving blf uris", ex);
    }
    
    // Return list
    return userBLFUriList;
}

Request Contexts

Request contexts can be used to fire requests asynchronously.



// Create BroadWorksProcess
BroadWorksProcess process = new BroadWorksProcess(getBroadWorksServer());

// Get Request Context
RequestContext context = process.getNewRequestContext();

// Fire Request Asynchrounously
context.put(new Request, response -> {
    // Consumer
    if (process.isError(response)) {
        // Do something
    }
});

// Fire Request Asynchrounously
context.put(new DifferentRequest, response -> {
    // Consumer
    if (process.isError(response)) {
        // Do something else
    }
});

// Wait for all requests to finish
context.join();

Information Builders

Information builders are a set of classes used to retrieve information about a BroadWorksObject. Information builders can be used to retrieve all information about a BroadWorks Object or just a subset of information based on your needs. Information Builders are available for Users, Groups, Enterprises, ServiceProviders, AccessDevice, and all service instances.

Retrieve All Information



    // Create a process to use for the builder
    BroadWorksProcess broadWorksProcess = new BroadWorksProcess(broadWorksServer);

    // Retrieve User from BroadWorks
    User user = User.getPopulatedUser(broadWorksServer, userId);

    // Build All Information For User
    UserInformation userInformation = new UserInformationBuilder(broadWorksProcess, user).all().execute();
    
    // Retrieve User Schedules from Information
    List schedules = userInformation.getUserSchedules();
    
    // Perform action with retrieved information
    ...

Retrieve Needed Information



    // Create a process to use for the builder
    BroadWorksProcess broadWorksProcess = new BroadWorksProcess(broadWorksServer);

    // Retrieve User from BroadWorks
    User user = User.getPopulatedUser(broadWorksServer, userId);

    // Build Only Schedule and Service Information For User - Note all other information will be null
    UserInformation userInformation = new UserInformationBuilder(broadWorksProcess, user).addUserSchedules().addUserServices().execute();
    
    // Retrieve User Schedules from Information
    List schedules = userInformation.getUserSchedules();
    
    // Perform action with retrieved information
    ...

Transform Plugins

Transforms plugins extend Alpaca's migration framework. Transformations happen before the migration target is moved to its destination. DeviceTypeTransform is included as an example.

Transforms must include the annotations @Component and @TransformComponent
The transform class should implement the interface for the type of migration the transform will occur during i.e. ServiceProviderMigrationTransform, UserMigrationTransform, etc.
The transform method will need to be implemented. After implementing the transform method, the project is ready to build.

Provisioning Plugins

Provisioning plugins are used when adding or deleting users and groups from BroadWorks using Alpaca.

Provisioning plugins must include the annotations @Component and @ProvisioningComponent.
The provisioning plugin class should implement one or more of the following interfaces: PreUserAddListener, PreGroupAddListener, PostUserAddListener, PostGroupAddListener, PreUserDeleteListener, PreGroupDeleteListener, PostUserDeleteListener, PostGroupDeleteListener.
The corresponding methods from the interfaces should be implemented i.e. preUserAdd, postGroupDelete.