Alpaca 9.1

Alpaca Server Configuration

This guide details all configurations that are available within the Alpaca Server. Starting in version 9.1 the Server configuration is centralized and accessible through the Eureka server. On Server startup it connects to the Eureka server and downloads the shared configuration file for all Alpaca Servers. See the Centralized Configuration section for more details.

Any changes to the configuration made while Alpaca is running will not take effect until after a restart. Use the following command to restart Alpaca - service alpaca-server restart.

YAML (YAML Ain't Markup Language)

All Alpaca configurations are in the YAML (.yml) format.

Basic Rules

  • YAML is case sensitive.
  • YAML does not allow the use of tabs. Spaces are used instead as tabs are not universally supported.

  • A dictionary is represented in a simple key: value form (the colon must be followed by a space):

        alpaca:
        migration:
          announcementRepositoryUsername: "BoNjOuRlEsAmIs049"
          announcementRepositoryPassword: "viveLEROILouis14"
          htmlEncodeExports: true

  • All members of a list are lines beginning at the same indentation level starting with a - (a dash and a space):

      broadworks:
    profileServer:
    - cluster: Production
      fileRepo: ProfileServer
      username: fileadmin
      password: P@ssw0rd
    - cluster: Lab
      fileRepo: ProfileServer
      username: fileadmin
      password: P@ssw0rd

  • Comments are denoted by #.

      # Alpaca Configuration
  alpaca:
      # Migration Configuration
      migration:
        announcementRepositoryUsername: "BoNjOuRlEsAmIs049"
        announcementRepositoryPassword: "viveLEROILouis14"
        htmlEncodeExports: true

Full Documentation

Complete YAML documentation can be found here.

Spring Boot

Alpaca Configurations are built upon Spring Boot. Within Spring there are a wide variety of pre-defined configurations. The complete list of configuration options can be found here.

Centralized Configuration

Centralized configuration allows management of all Alpaca Servers using a single configuration file. To enable this, configuration of the /etc/alpaca/server/config/bootstrap.yml must be completed so that the Alpaca Server can retrieve its initial configuration file. This is a sample bootstrap.yml configuration file.

spring:
  cloud:
    config:
      name: alpaca-server
      uri:
        - http://alpaca:alpaca@alpaca-1.lab.ecg.co:8761/config
        - http://alpaca:alpaca@alpaca-2.lab.ecg.co:8761/config
        - http://alpaca:alpaca@alpaca-3.lab.ecg.co:8761/config
eureka:
  client:
    service-url:
      defaultZone: http://alpaca:alpaca@alpaca-1.lab.ecg.co:8761/eureka,http://alpaca:alpaca@alpaca-2.lab.ecg.co:8761/eureka,http://alpaca:alpaca@alpaca-3.lab.ecg.co:8761/eureka

Spring Cloud Config (spring.cloud.config)

  • name: This is the name of the Alpaca Server used to determine the configuration file to retrieve. This is the exact name of the file on the config server without the profile. So in this example, if the server is running in production mode, the configuration file would be named alpaca-server-prod.yml.
  • uri: This is an array of Eureka servers with which to retrieve the configuration. The centralized configuration server is located on the Eureka server. So this should be the same domain, port, and credentials as the Eureka server. It contains the path segment for the configuration context as configured on the Eureka server. This defaults to /config.

Eureka Client Service URL (eureka.client.service-url)

  • defaultZone: This is the Eureka servers to register against. This will be a comma separated list of Eureka servers to register against. This will include the username and password as configured in the Eureka configuration. The path will be /eureka as default configured.

Example Configuration

This sample configuration is meant as a guide only. Do not copy and paste the entire content into your configuration.

org:
  jobrunr:
    dashboard:
      username: jobrunr
      password: jobrunr
alpaca:
  auditLogs:
    fireAlertsForTasks: false
    retentionDays: -1
    skipReads: true
  access-logs:
    access-log-format: "%h %l %u %t "%r" %s %k %b %T %D "%{Referer}i" "%{User-Agent}i""
  broadworks:
    connectionTimeoutMillis: 60000
    sslPermissive: true
    requireDomainOnCredentialAdd: false
    update-alpaca-user-credentials-cn-change: false
  client:
    hideEnableCiscoSoftClient: true
    hideAuthenticationReset: false
    header-text: 'BW Web Portal'
    header-image-u-r-l: 'images/logo.svg'
    always-remember-me: true
    style-sheets:
      - 'css/custom.css'
    am-charts:
      primary-colors:
        - "#653E4C"
        - "#7E4E60"
        - "#985D73"
        - "#AA7488"
        - "#B98D9D"
        - "#C9A6B3"
        - "#D8C0C9"
      complementary-colors:
        - "#412E1B"
        - "#715438"
        - "#916E4B"
        - "#B0875E"
        - "#C3A17F"
        - "#DBBA99"
        - "#EED3BA"
    logout-redirects-to-login: true
    enable-user-passcode-reset-without-previous-passcode: false
    breadcrumb-visibility:
      user:
        USER: 0
    hidden-navs:
      user.history:
        - USER
      user.registrations:
        - USER
        - GROUP
    deviceNameConfig:
      deviceNameTemplate: "{deviceName}"
      templateList:
        - name: "PolyTemplate"
          template: "PolyTemplate_{mac}"
          subtypes:
            - "Polycom VVX 600": "Polycom_VVX_600_{mac}"
            - "Polycom VVX 500": "Polycom_VVX_500_{mac}"
            - "Polycom VVX 300": "Polycom_VVX_300_{mac}"
            - "Polycom VVX 410": "Polycom_VVX_410_{mac}"
    userReplace:
      userIdMask: "New User Id"
      userIdPattern: "^[A-Za-z0-9._%+-]"
  communigate:
    communigateClusterNickname: "Cluster1"
    communigateServiceProviderId: "Voice_Mail_Only"
    communigateLoginDisabledEmail: "voip.admin@acme.com"
    communigateVoicemailDnLength: 10
  fileStore:
    location: /opt/alpaca/filestore
    task-file-retention-period-months: 1
    report-file-retention-period-months: 6
    temp-file-retention-period-days: 90
    use-s3: false
    s3-endpoint: "https://s3.amazonaws.com"
    s3-region: "us-east-1"
    bucket-name: ""
    access-key-id: ""
    secret-access-key: ""
  mail:
    baseUrl: http://127.0.0.1:8080
    from: alpaca.alerts@email.com
  migration:
    announcementRepositoryUsername: "BoNjOuRlEsAmIs049"
    announcementRepositoryPassword: "viveLEROILouis14"
    authenticationUsernameChangeableRegex: ".*(Polycom|Linksys|Cisco).*"
    authenticationPasswordChangeableRegex: ".*(Polycom|Linksys|Cisco).*"
    blfCachingEnabled: true
    deviceFileMigrationRuleList:
      - deviceTypeRegex: ".*(Polycom|Linksys|Cisco).*"
        fileRegexes: [
            "%BWMACADDRESS%-directory.xml",
            "%BWMACADDRESS%-calls.xml",
        ]
    deviceRebootDelayMillis: 5000
    htmlEncodeExports: true
    ignoreLinePortTransforming: false
    updateExpiredConferenceSchedules: true
    userDeletionDuringGroupDestroyThreshold: 450
    ignoreNSSyncError: false
  security:
    allowRegistration: true
    maxFailedLoginAttempts: 5
    rememberMe:
      key: XxXxXxXxXxXxXxXxXxXxXxXxX
    ip-fencing:
      SYSTEM:
        - "0.0.0.0/0"
      USER:
        - "192.168.0.1/24"
        - "192.168.0.2/24"
    password:
      enforceNistPasswordRules: true
      minLength: 12
      blacklist:
        - "password"
        - "secret"
        - "ecg"
  cisco-soft-client:
    copy-user-id-to-email: true
    service-pack-definitions:
      - service-pack-name: "UC Connect - AddOn"
        service-names:
          - Authentication
          - "Client License 17"
          - "BroadTouch Business Communicator Tablet - Video"
          - "Shared Call Appearance"
      - service-pack-name: "Communicator - AddOn"
        service-names:
          - Authentication
          - "Client License 17"
          - "BroadTouch Business Communicator Tablet - Video"
          - "Shared Call Appearance"
    mobile:
      enabled: true
      device-type-name: "Connect - Mobile"
      service-pack-name: "UC Connect - AddOn"
      line-port-template: |
        'connect-mobile-' + user.userId + "@domain.com"
      device-name-template: |
        'connect-mobile-' + user.userId.split('@')[0]
    tablet:
      enabled: false
      device-type-name: "Connect - Tablet"
      service-pack-name: "UC Connect - AddOn"
      line-port-template: |
        'connect-tablet-' + user.userId + "@domain.com"
      device-name-template: |
        'connect-tablet-' + user.userId.split('@')[0]
    desktop:
      enabled: true
      device-type-name: "Communicator - Desktop"
      service-pack-name: "Communicator - AddOn"
      line-port-template: |
        'connect-desktop-' + user.userId + "@domain.com"
      device-name-template: |
        'connect-desktop-' + user.userId.split('@')[0]
  bulk-provisioning:
    default-domain: acme.com
    sip-default-domain: sip.acme.com
    voicemail-email-domain: acme.com
    default-passcode: 1234
    default-password: "ChangeMe1!"
  license-entry:
    cleanup-interval: 365
    graphed-licenses:
      - "BusinessLine"
      - "Standard"
      - "PersonalMobility"
      - "Premium"
      - "CallCenterAgent"
      - "CallCenterSupervisor"
  number-inventory-management:
    enabled: true
    default-rate-center: "RateCenter1"
    country-codes:
      - "1"
    aging-period: 45
  tasks:
    task-difficulty-alert: 10000
    task-difficulty-refusal: 100000
broadworks:
  asynchronousTimeoutMillis: 12000
  autoFireMillis: 1000
  connectionReconnectAttempts: 4
  connectionReconnectDelayMillis: 500
  encoding: "ISO-8859-1"
  maxRequestsPerSecond: 40
  maxRetriesForSystemError: 3
  numberOfSocketsPerServer: 1
  trusted-host: true
  profileServer:
    - cluster: Production
      fileRepo: ProfileServer
      username: fileadmin
      password: P@ssw0rd
    - cluster: Lab
      fileRepo: ProfileServer
      username: fileadmin
      password: P@ssw0rd
  synchronousTimeoutMillis: 60000
  validateRequestsOnFire: false
communigate:
  host: communigate.server
  port: 106
  login: postmaster
  password: password
spring:
  rabbitmq:
    host: rabbitmq
    username: rabbitmq
    password: rabbitmq
  data:
    mongodb:
      database: alpaca
      uri: mongodb://localhost:27017
  mail:
    host: smtp.gmail.com
    password: "emailPassword!"
    port: 587
    properties.mail.smtp:
      auth: true
      ssl.trust: smtp.gmail.com
      starttls.enable: true
    protocol: smtp
    username: alpaca.alerts@email.com
  servlet:
    multipart:
      location: tmp
      maxFileSize: 1000MB
      maxRequestSize: 1000MB

JobRunr (org.jobrunr)

  • dashboard.username: The access username to log into the JobRunr dashboard to view scheduled Alpaca tasks.
  • dashboard.password: The access password to log into the JobRunr dashboard.

Alpaca (alpaca)

alpaca is the root header for Alpaca Server related configurations.

Audit Logs (auditLogs)

Audit log configurations control what happens when Alpaca is parsing audit logs from BroadWorks.

  • fireAlertsForTasks: If disabled, Alpaca will not fire alerts for audit logs that are the result of a task that Alpaca started, i.e. Enterprise Migration.
  • retentionDays: The number of days audit logs are retained for. -1 will cause the audit logs to be retained indefinitely.
  • skipReads: If set to true, audit logs that are "reads" will be ignored by Alpaca.

Access Logs (access-logs)

Access log configurations control how to read in Apache Access logs from the BroadWorks XSP.

  • access-log-format: The log format that is used on your BroadWorks XSP. This can usually be found in the Tomcat server.xmlunder com.broadsoft.xsp.platform.AccessLogValve.pattern.

BroadWorks (broadworks)

Alpaca server configurations that relate to BroadWorks.

  • connectionTimeoutMillis: How long before an un-answered request is deemed timed out.
  • sslPermissive: Whether to disable SNIExtension and use a universal trust strategy for SSL.
  • requireDomainOnCredentialAdd: Whether or not a domain is required when credentials are being added for a BroadWorks Cluster.
  • update-alpaca-user-credentials-cn-change: Defaults to false. If set to true, when a BroadWork User's password is updated within Alpaca and that User has an associated AlpacaUser, the AlpacaUser's credentials will also be updated.

Client (client)

Client configurations affect items that are seen on the Alpaca Server web interface.

  • hideAuthenticationReset: If set to true, the SIP Authentication Reset action will be hidden from Users.
  • hideEnableCiscoSoftClient: If set to true, the Enable Cisco Soft Client action will be hidden from Users.
  • header-text: Text to be displayed in the header bar. Default is 'Alpaca'. If nothing is provided, text will be removed from the header.
  • header-image-u-r-l: Url to an image to be used in the header. If nothing is provided, no image will appear in the header. A height of 50px or smaller is recommended. Images stored locally should be put in <ALPACA_HOME>/static/images/.
  • logout-redirects-to-login: Defaults to true. When true, after logging out the user will be redirected to login. When false, the user will be redirected to a logout complete page.
  • enable-user-passcode-reset-without-previous-passcode: Defaults to false. Allows Alpaca Users with BroadWorks LoginType USER, to update their BroadWorks Voice Portal Passcode without providing the previous passcode.
  • style-sheets: An array of URLs (can be relative) that will be used by Alpaca as CSS. This will replace the existing style sheet and is intended to be used with the Alpaca styling project for branding.
  • am-charts.primary-colors: An array of quoted HEX HTML colors to be used as primary colors for the licensing chart. These default to the Alpaca slate palette.
  • am-charts.secondary-colors: An array of quoted HEX HTML colors to be used as secondary colors for the licensing chart. These default to the Alpaca brown palette.
  • always-remember-me: Defaults to true. If true, all logins request will automatically have remember-me set to true. If false, a Remember-Me checkbox will appear on the login page and the User will be able to choose whether or not to use it.
  • allow-archive-bypass: If set to true, an option to bypass archive will appear for some delete tasks within Alpaca. Defaults to false.

Configuration to change the visibility and depth of Alpaca breadcrumbs based off of BroadWorks login types.

  • Model

client:
  breadcrumb-visibility:
    page-name:
      LoginType1: Depth
      LoginType2: Depth
  • Example

client:
  breadcrumb-visibility:
    user:
      USER: 0
      GROUP: 1
    group:
      GROUP: 0
  • Example explanation

In the above example, we are configuring the bread crumb visibility for the User and Group pages. We have set USER login type to a depth of 0 and Group login type to a depth of 1 for the User page and we have set Group login type to a depth of 0 for the group page. A depth of 0 means that only the current level is visible and none of the higher breadcrumbs will be displayed. A depth of 1 means that the current level and one level above is visible in the bread crumb chain. In this example, if a Group admin was to navigate to the User's page, they would see the User's breadcrumb, as well as their own breadCrumb. If the depth was set to 2, the Group admin would also see the Service Provider/Enterprise breadcrumb. Depending on the page and login type, a depth of 0-4 can be used. If no configuration is provided, all breadcrumbs will be displayed.

  • Supported Login Types

    • USER
    • GROUP
    • DEPARTMENT
    • SYSTEM

  • Page Options

    • user
    • group
    • service-provider
    • cluster
    • group-access-device
    • sp-access-device
    • system-access-device

Hidden Navs (hidden-navs)

Configuration to hide individual nav tabs based on BroadWorks login type.

  • Model

client:
  hidden-navs:
    page-name.tab-name:
      - LoginType1
      - LoginType2
  • Example

client:
  brreadcrumb-visibility:
    user.registrations:
      - USER
      - GROUP
    user.history:
      - USER

In the above example, USER and GROUP login types would not be able to the Registrations tab on the User's page. Also USER login types would not be able to see the history tab on the User's page. If no configuration is provided, all tabs will be visible.

  • Page Options
    • user
    • group
    • service-provider
    • cluster
    • group-access-device
    • sp-access-device
    • system-access-device
    • admin

Device Name Config (deviceNameConfig)

Configuration to determine Device naming during a Device Migration.

  • deviceNameTemplate: Default template used for renaming the device. This is used if a template value is not supplied for a matched entry from the template list. Valid template replacement values are:
    • {deviceName}: The device's current name.
    • {deviceType}: The device's type.
    • {mac}: The device's MAC address.
  • templateList : Templates for Device's with potential subtypes.
    • name : Name of the templated DeviceType. This must match the name of a DeviceType in BroadWorks.
    • template : Default template for this type. This value will determine the Device's final name if a subtype is not selected.
    • subtypes : A map of Device Types to Device Type templates. The Device Type keys will appear in the Alpaca client under the selected template name. The template value will determine the Device's final name.

User Replace (userReplace)

Configurations used for the User Replace task.

  • userIdMask: The title that will be used for the user id field in the User Replace wizard.
  • userIdPattern: The regex pattern that the new user id for User Replace must match.

CommuniGate (communigate)

Client configurations used for the CommuniGate Voicemail tool.

  • communigateClusterNickname: The nickname of the BroadWorks cluster to associate Communigate with.
  • communigateServiceProviderId: This is the Service Provider ID that Users will be created within.
  • communigateLoginDisabledEmail: Where login disabled assistance requests will be sent.
  • communigateVoicemailDnLength: The required number length for User creation. This is validated by the client.
  • mailServerDomains: List of mail server domain options to be used with the Communigate Voicemail Tool.

File Store (fileStore)

Configurations that deal with the Alpaca Filestore.

  • location: The absolute or relative location on the filesystem where exported files will be stored.
  • task-file-retention-period-months: The number of months retain tasks and the files (logs, attachments, etc.) associated with the task. Defaults to 1 month. If set to 0 or below, tasks will not be cleaned up.
  • report-file-retention-period-months : The number of months retain reports and the files (logs, attachments, etc.) associated with the report. Defaults to 6 months. If set to 0 or below, tasks will not be cleaned up.
  • temp-file-retention-period-days : The number of days to retain temporary files generated from tasks and reports. Defaults to 15 days. If set to 0 or below, tasks will not be cleaned up.
  • use-s3: Enables the use of S3 buckets to store Alpaca files. This is required when using HA clustering so that each server has access to associated logs and files for download.
  • s3-endpoint: The S3 endpoint, e.g. "https://s3.amazonaws.com"
  • s3-region: The region that the S3 bucket belongs. e.g. "us-east-1"
  • bucket-name: The S3 bucket name to use.
  • access-key-id: The S3 access key id.
  • secret-access-key: The S3 secret access key.

Mail (mail)

Configurations for sending emails from Alpaca.

  • baseUrl: The URL of the Alpaca server that the emails will be sent from.
  • from: The email address to send emails from.

Migration (migration)

Configurations used for performing various migrations within Alpaca.

  • announcementRepositoryUsername: The username to retrieve voice portal audio and video files from for migration procedures.
  • announcementRepositoryPassword: The password to retrieve voice portal audio and video files from for migration procedures.
  • authenticationPasswordChangeable: When randomizing a user's authentication password, the user's access device type must match the provided regular expression.
  • authenticationUsernameChangeable: When randomizing a user's authentication username, the user's access device type must match the provided regular expression.
  • blfCachingEnabled: When BLF caching is enabled, Alpaca will parse through all BLF entries and keep an updated database of monitoring users. This can cause startup to take a little longer but it will improve the speed of migrations.
  • deviceFileMigrationRuleList: Migration file rules consist of device types matched to the files that should be migrated with the device. There can be any number of file rules that specify the desired files to be migrated. If no rules are provided, no device files will be migrated during any type of migration.
  • deviceFileMigrationRuleList/deviceTypeRegex: This defines the file rule device type, as specified by regular expression.
  • deviceFileMigrationRuleList/fileRegexes: Any number of files can be specified by exact name.
  • deviceRebootDelayMillis: The delay in milliseconds between rebooting the device and performing the migration procedure.
  • htmlEncodeExports: When performing an export, special characters will be escaped if this option is turned on. Characters include <, >, &, =, and '.
  • ignoreLinePortTransforming: Only applies to line ports with the source default domain. If set to true, line ports with the source default domain, will not have their domain transformed to the destination default domain.
  • updateExpiredConferenceSchedules: If true, during a migration, expired Meet Me Conferences will be updated to the current time. Otherwise, the conference will not be migrated.
  • userDeletionDuringGroupDestroyThreshold: If a Group has more users than the threshold, each user will be individually deleted instead of being deleted as a part of the Group delete request.
  • ignoreNSSyncError: Configuration that will ignore an NS SYNC error returned from BroadWorks during a VoiceVPN Get Request call.

Security (security)

Configurations that can be used to make Alpaca more or less secure.

  • allowRegistation: If true, Users will be able to register via the registration page, otherwise they will have to be manually added by an admin.
  • maxFailedLoginAttempts: The number of failed login attempts before an Alpaca User is locked out of their account. Defaults to 5 failed attempts.
  • rememberMe.key: A unique key used for remember-me tokens
  • ip-fencing: Map of BroadWorks login type (SYSTEM, USER) to the allowed source subnets. If an Alpaca User of a provided type attempts to login from outside the provided ip space, login will be denied. If ip-fencing is not provided, logging in from anywhere is allowed.

Password (password)

Configurations for Alpaca User passwords.

  • enforceNistPasswordRules - If enabled, passwords must conform to NIST 5.1.1.2. Passwords cannot contain the Username, repeating digits, ascending or descending characters, and must have a minimum length of 8 characters. If disabled, only a minimum length of 8 will be enforced.
  • minLength - Password minimum length. Only used when enforceNistPasswordRules is set to true. Defaults to 8, minimum value is 8.
  • blacklist - List of phrases or character sequences that cannot be included in the password. Only used when enforceNistPasswordRules is set to true.

Cisco Soft Client (cisco-soft-client)

Configurations that can be used to control the way that Alpaca provisions services related to Cisco Soft clients.

  • enable-allow-call-retrieve: Controls whether the SCA Allow Call Retrieve option is enabled for the user. Defaults to no change.
  • enable-allow-bridging: Controls whether the SCA Allow Bridging option is enabled for the user. Defaults to no change.
  • enable-imp: Controls whether the Integrated IMP service is enabled for the user. Defaults to no change.
  • copy-user-id-to-email: When enabled, the user's email address (located in BroadWorks User Profile) will be set as their User id.
  • service-pack-definitions: An array of service packs that will be created and authorized on the Service Provide and Group when provisioning Cisco Soft clients.
  • service-pack-definitions/service-pack-name: The name of the service pack.
  • service-pack-definitions/service-names: An array of the services to be added to the service pack. The names listed MUST match the name used in the BroadWorks Licenses. They are NOT necessarily the user friendly name displayed in the BroadWorks web interface. (Ex: Integrated IMP is displayed as Integrated IM&P in the BroadWorks web interfaces, but BroadWorks OCI requires Integrated IMP instead.)
  • mobile: Sub-elements of mobile control the provisioning of mobile endpoints for Cisco Soft clients.
  • mobile/enabled: Controls whether mobile devices are provisioned as part of the Cisco Soft client provisioning task. Defaults to true.
  • mobile/device-type-name: The name of the Device Type to use for mobile devices. This device type must already exist in the system.
  • mobile/service-pack-name: The name of the Service Pack to assign to the user when provisioning a mobile device.
  • mobile/line-port-template: This template defines a Spring Expression Language (SpEL) statement used to calculate the line-port for the mobile device.
  • mobile/device-name-template: This template defines a Spring Expression Language (SpEL) statement used to calculate the device-name for the mobile device.
  • tablet: Sub-elements of tablet control the provisioning of tablet endpoints for Cisco Soft clients.
  • tablet/enabled: Controls whether tablet devices are provisioned as part of the Cisco Soft client provisioning task. Defaults to true.
  • tablet/device-type-name: The name of the Device Type to use for tablet devices. This device type must already exist in the system.
  • tablet/service-pack-name: The name of the Service Pack to assign to the user when provisioning a tablet device.
  • tablet/line-port-template: This template defines a Spring Expression Language (SpEL) statement used to calculate the line-port for the tablet device.
  • tablet/device-name-template: This template defines a Spring Expression Language (SpEL) statement used to calculate the device-name for the tablet device.
  • desktop: Sub-elements of desktop control the provisioning of desktop endpoints for Cisco Soft clients.
  • desktop/enabled: Controls whether desktop devices are provisioned as part of the Cisco Soft client provisioning task. Defaults to true.
  • desktop/device-type-name: The name of the Device Type to use for desktop devices. This device type must already exist in the system.
  • desktop/service-pack-name: The name of the Service Pack to assign to the user when provisioning a desktop device.
  • desktop/line-port-template: This template defines a Spring Expression Language (SpEL) statement used to calculate the line-port for the desktop device.
  • desktop/device-name-template: This template defines a Spring Expression Language (SpEL) statement used to calculate the device-name for the desktop device.

Service Packs specified in the mobile, tablet, and deskstop sections are normally defined in service-pack-definitions.

Bulk Provisioning (bulk-provisioning)

Configurations that can be used to control the way that Alpaca treats certain fields during Bulk Provisioning.

  • default-domain: Domain used for User's if one is not explicitly provided. If not provided, defaults to the Group's default domain.
  • sip-default-domain: Domain used for the User's primary line/port if one is not explicitly provided. If not provided, defaults to the Group's default domain.
  • voicemail-email-domain: Domain used for User's Voice Messaging setting if one is not explicitly provided. If not provided, defaults to the Group's default domain.
  • default-passcode: Default passcode to use for Users if one is not explicitly provided. Defaults to random.
  • default-password: Default password to use for Users if one is not explicitly provided. Defaults to random.
  • default-voicemail-mode: The default Voicemail Mode to use when setting up voicemail. Options are 'FORWARD' or ' UNIFIEDGROUP'. Defaults to UNIFIEDGROUP.
  • default-blf-uri-domain: Domain used for User's BLF URI setting if one is not explicitly provided. If not provided, defaults to the Group's default domain.

License Entry (license-entry)

Configurations to control monitoring of BroadWorks licenses.

  • cleanup-interval: Defaults to 365. The number of days that a license entry will remain in the Alpaca database.
  • graphed-licenses: The BroadWorks licenses to display in the License Usage graph. Default licenses are: " BusinessLine", "Standard", "PersonalMobility", "Premium", "CallCenterAgent", "CallCenterSupervisor". License names can be found on the BroadWorks AS_CLI under System/Licensing. Limited to 7 licenses. If more than 7 are provided, only the first 7 will be used.

Tasks (tasks)

  • trunkGroupUserCreationMonitorMinutes: How long to monitor for a BroadWorks TrunkGroupUserCreation task to complete. Defaults to 15 minutes.
  • taskDifficultyAlert: The difficulty threshold that has to be crossed for a warning alert when about to run a task. Defaults to 10000. To disable, set to -1.
  • taskDifficultyRefusal: The difficulty threshold that has to be crossed for Alpaca to refuse running a task. Defaults to 100000. To disable, set to -1.

Number Inventory Management (number-inventory-management)

Configurations for controlling the Number Inventory Management feature.

  • enabled: Whether or not the feature is enabled. Defaults to false.
  • default-rate-center: The rate center to assign to numbers within the system.
  • country-codes: List of country codes that your BroadWorks System uses. Defaults to ["1"].
  • aging-period: The number of days a number has to age before returning to the Available or Reserved state. Defaults to 45.

Broadworks (broadworks)

broadworks is the root header for Alpaca Library related configurations.

  • asynchronousTimeoutMillis: Timeout for asynchronous calls.
  • autoFireMillis: When using a RequestBundler this timeout controls how long to wait before firing a request with less than 15 entries.
  • connectionReconnectAttempts: How many times to attempt a reconnect to BroadWorks once a connection is lost.
  • connectionReconnectDelayMillis: How long after a connection lost to attempt to reconnect.
  • encoding: The encoding to use for the outgoing and incoming parsing of BroadWorks messages.
  • maxRequestsPerSecond: The maximum number of requests to send per second through a single BroadWorksServer object. This is a blocking operation that will limit the overall speed of the code if attempting to perform too many operations per second.
  • maxRetriesForSystemError: The number of times to retry a request if it comes back as a System Error.
  • numberOfSocketsPerServer: How many sockets will be opened per BroadWorksServer connection.
  • synchronousTimeoutMillis: Timeout for synchronous calls.
  • validateRequestsOnFire: Sets if JSR 303 Bean Validation will be used to verify that a request is valid per the XML spec before sending it to BroadWorks. The Request will not be sent if invalid.
  • trustedHost: Whether or not the Alpaca server is in the External Authentication network access list on the XSP and Application Servers. Required for Single Sign-On.

File Repository (profileServer)

Configurations used for connecting Alpaca to a BroadWorks file repository (usually a profile server).

  • cluster: The nickname of the cluster configured in Alpaca.
  • file-repo: The file repository name in BroadWorks.
  • password: The password of the file repository admin.
  • username: The username of the file repository admin.

Communigate (communigate)

Configurations used for connecting Alpaca to a CommuniGate Voicemail server for use with the Alpaca CommuniGate Voicemail Tool.

  • host: The hostname or IP address of the CommuniGate server to connect to.
  • port: The CLI port for the Communigate server. This defaults to 106.
  • login: The admin login to use to perform changes. The account must have permissions to create, modify, and delete accounts for the desired domain.
  • password: The password for the associated login.

Spring (spring)

MongoDB (data.mongo)

The MongoDB configuration can be put in the data portion of your application-prod.yaml configuration file.

  • database: The name of the database to use for Alpaca. This should always be alpaca.
  • uri: The address of the local Mongo installation. This is typically mongodb://localhost:27017.

Email (mail)

  • host: The server to connect to.
  • password: The password for the email account that is being used.
  • port: The port to connect to. Defaults to 25.
  • protocol: The protocol to use to send the email, i.e. SMTP, POP3, IMAP.
  • properties.mail.smtp: Mail properties if using SMTP.
    • auth: If true, attempt to authenticate the user using the AUTH command. Defaults to false.
    • ssl.trust: If set to "*", all hosts are trusted. If set to a whitespace separated list of hosts, those hosts are trusted. Otherwise, trust depends on the certificate the server presents.
    • starttls.enable: If true, enables the use of the STARTTLS command (if supported by the server) to switch the connection to a TLS-protected connection before issuing any login commands. Note that an appropriate trust store must be configured so that the client will trust the server's certificate. Defaults to false.
  • username: The email account to use to send emails from.

File Upload (servlet.multipart)

  • location: Intermediate location of uploaded files.
  • max-file-size: Max file size. Values can use the suffixes "MB" or "KB" to indicate megabytes or kilobytes, respectively. Defaulted to 1000MB. Setting to -1, makes the file size unlimited.
  • max-request-size: Max request size. Values can use the suffixes "MB" or "KB" to indicate megabytes or kilobytes, respectively. Defaulted to 1000MB. Setting to -1, makes the request size unlimited.

RabbitMQ (rabbitmq)

  • host: A comma separated list of RabbitMQ servers to connect to. This is used for events and messaging to clients.
  • username: The RabbitMQ username to use.
  • password: The RabbitMQ password to use.

SSO Configuration

Single Sign-On is an Alpaca feature that allows registration and association with BroadWorks through a 3rd party authentication provider. The requirements and usages guide can be found in the concepts guide.

Configurations (spring.security)

OAuth/OAuth2 (oauth/oauth2) 
spring:
  security:
    oauth2:
      client:
        registration:
          google:
            client-id: id-provided-by-provider
            client-secret: secret-provided-by-provider
            client-name:
            scope: email
        provider:
          google:
            issuer-uri: https://accounts.google.com
  • registration.{service-name}: A name for the client that can be any value the configurer would like. In this example, the name is google but it could be any OAuth provider or even the value SSO. This value is shown to the end user as a capitalized value to select during login.
  • registration.{service-name}.client-id: This is provided by the OAuth registration provider.
  • registration.{service-name}.client-secret: This is provided by the OAuth registration provider.
  • registration.{service-name}.client-name: This is provided by the OAuth registration provider.
  • registration.{service-name}.scop: This should be set to email.
  • provider.{service-name}: This value must match the value in the registration name. It is also dynamic but must match the previously configured value.
  • provider.{service-name}.issuer-uri: This is the URI as given by the specified authorization server. Examples:
    • Google: https://accounts.google.com
    • Okta: https://{{project}}.okta.com/oauth2/default
SAML2 (saml2) 
spring:
  security:
    saml2:
      relyingparty:
        registration:
          okta:
            signing.credentials:
              - private-key-location: "classpath:credentials/rp-private.key"
                certificate-location: "classpath:credentials/rp-certificate.cert"
            identityprovider:
              entity-id: http://www.okta.com/xxxxxxxxxxx
              verification.credentials:
                - certificate-location: "classpath:credentials/idp-certificate.cert"
              singlesignon.url: sso.url.account.xyz
              singlesignon.sign-request: true
  • registration.{service-name}: A name for the client that can be any value the configurer would like. In this example, the name is okta but it could be any SAML provider or even the value SSO. This value is shown to the end user as a capitalized value to select during login.
  • private-key-location: The private key of the Relying Party. In this example location, the key is in the classpath of Alpaca. Valid directories for this are /opt/alpaca and /etc/alpaca/server. Example full path for certificates and keys: /etc/alpaca/server/credentials/*
  • certificate-location: The certificate of the Relying Party. See private-key-location for location assistance.
  • entity-id: The ID/URL provided by SAML provider.
  • verification.credentials.certificate-location: The certificate of the SAML identity provider. See private-key-location for location assistance.
  • singlesignon.url: The authentication URL as provided by the SAML provider.
  • singlesignon.sign-request: false: Whether or not the SSO request is signed. Defaults to true.

Profiles

  • prod: This is the primary configuration for production.
  • sso: Enables Single Sign On. See the SSO Configuration

Profile selection can be done in the /ALPACA_HOME/configuration file. See below.

# The Alpaca profiles to run
# See available options: https://guides.ecg.co/alpaca/latest/configuration/#profiles
export PROFILES=prod

Configure AlpacaStore Cleanup Process

Alpaca is configured to remove older JSON files from migrations and exports after 90 days by default. If the default needs to be changed, review the following steps.

  1. In the application-prod.yml configuration file, locate the file-store configuration under alpaca.

  2. Change the cleanup-interval value to the desired number of days to retain files within the configured location.

Alpaca CLI (alpaca.cli)

Configurations can be modified in the application-prod.yml file located in the Alpaca CLI config directory. Configuration for the CLI are used to connect it to the Alpaca Server.

  • serverScheme: The scheme to use to connect to the alpaca server. HTTPS is the only scheme that is currently supported.
  • serverAddress: The address of the alpaca server.
  • serverPort: The port to use to connect to the alpaca server.
  • sslPermissive: Whether or not to be permissive with insecure SSL (such as self-signed certificates).
alpaca:
  cli:
    serverScheme: https
    serverAddress: localhost
    serverPort: 8443
    sslPermissive: true

JAVA_HOME

Required Java versions as of Alpaca 8.0.0:

  • Alpaca Server - Java 11
  • Alpaca Remote - Java 8

If the server that Alpaca Server or Remote is installed is running multiple versions of Java, and the required version for Alpaca is not the default, the JAVA_HOME variable for Alpaca can be manually set in the /ALPACA_HOME/configuration file. See below:

# Java Home
export JAVA_HOME=/usr/lib/jvm/<required_java_version>