About This Guide

The purpose of this guide is to describe implementation and workflow of Bulletin application integration with OSA.

Audience

The guide is aimed for provider system administrators and engineers.

Terms and Abbreviations

APS – Application Packaging Standard, an open standard that was designed to simplify the delivery of SaaS applications in the cloud-computing industry.

OSA – Odin Service Automation

OBA – Odin Business Automation.

Provider - The service provider operating OAP 7.x or newer

Customer, Subscriber – Individual customer or company who purchases services from Provider

End User – Service user of service provisioned for Customer through OSA Provider Control Panel (PCP) – Browser-based control panel for the Provider Customer Control Panel (CCP) – Browser-based control panel for the Customers. MyCP – Browser-based control panel for the End User

Reseller - Reseller of Bulletin services


Localization List

Bulletin has been localized in the following languages for each category

  • Customer Interface
    • EN
  • Bulletin API error messaging
    • EN
  • Bulletin external communication to customer
    • EN


Business Model Overview

Bulletin provides SaaS mobile messaging solutions for the 2-way delivery of text messages between computer or web applications, and mobile phones or devices. Bulletin Messenger allows organizations of all sizes to connect with mobile users on any device, anywhere in the world.

Integration / Customer Workflow


The integration workflow looks as follows:

  • Deploying Bulletin application endpoint.
    • The step is performed once. For details, refer to the Deploying Application Endpoint Section of this guide.
  • Importing Bulletin application package
    • The step is performed once. For details, refer to the Importing Application Package Section of this guide.
  • Creating service instances in Provider Control Panel.
    • For details, refer to the Creating an Instance of Application section of this guide.
  • Creating required resource types.
    • For details, refer to the Creating Resource Types sections of this guide.
  • Creating service template.
    • For details, refer to the Creating Service Template section of this guide


Customer’s Lifecycle

Bulletin allows the customer to use the service after the initial setup work flow is complete. If the customer wishes to upgrade plans, or subscriptions etc., they can do so at any time in the billing cycle.

Partner Agreement

Before proceeding with the steps in this document, the provider must contact Bulletin and establish a reseller/partner agreement with them. Bulletin should then be able to provide the plan and API details, which are used to provision the Bulletin package. Details on which fields will be needed are described in the Resource Configuration section of this document. Contact Bulletin at https://www.bulletin.net/contact.html


Technical Integration Overview

This section contains an outline of how the integration of Bulletin and OSA is performed and the list of Bulletin features that are supported within the integration package.

General Architecture

The following scheme represents the architecture of OSA and Bulletin integration:





Resource Descriptions Provider Side

  • Bulletin API – Basic credentials necessary for API calls and logging settings.
  • Email Template – Template for welcome mail
  • Plans – Plans are used to define sms limits for service plans


Resource Descriptions Customer Side

  • Company – Basic auto provision resource.
  • Users –Bulletin users linked to service users
  • Plan id – counter for plans(one plan per service plan
  • Bulletin_smsusage – counter for tracking sms usage
  • Bulletin_smsusage_all – counter for tracking sms usage.

Admin Level:

  • Download Bulletin APS package from APS catalogue.
  • Install the APS package in OSA.
  • Fill all the necessary API details and Log settings.
  • Create the email template instance.
  • Create the plans instance.
  • Provider can view the SMS usage report.
  • Create all the application service, service reference and counter resource types and service templates in OSA.
  • Create service plans for different SMS limit plans with upgrade/downgrade option and publish them to online store in OBA for customers’ consumption.

End user Level:

  • OAP end user will go to OAP online store.
  • Select the desired Bulletin service plan from the online store.
  • Select the subscription period.
  • Create a new user or use the existing user account.
  • Continue with the billing steps.
  • Once billing is done, the application will be provisioned for the user using values from the global settings.
  • Log in to customer account. Customer can see the new subscription under the available Bulletin subscription list based on the plan he purchased.
  • Customer can see SMS limit and SMS usage details.
  • Customer can log in to Bulletin portal as admin user.
  • Customer can create company users as service users.
  • Customer can switch to another service plan


Service users

  • Login to MyCP control panel.
  • Users can edit his/her details.
  • Users can login to Bulletin portal as users.


Components

OAP Admin
OAP Customer Manager
Bulletin portal
Imports APS package
Provisions Bulletin Account, Plan and users
Managing Bulletin account and associated plans
Configures package and resource settings
Switch between plans


Integration Prerequisites

Before you start integrating Bulletin into OSA, learn about necessary preparations to the process.


Prerequisites for Bulletin Application

Bulletin requires that your OSA and endpoint servers have the downloaded and configured Bulletin APS package as per this Deployment Guide and OSA provisioning host is configured with PHP and allowed to execute the PHP scripts contained in the APS package and make the required API calls to Bulletin.


Deploying Application Endpoint

To deploy the Bulletin APS application on the Provisioning Host, you need to import and configure the Bulletin APS Package. Find information about how to do it in this section.

Note: Both OAP and Endpoint servers should be in same IP sub network.

The following table lists the hardware and software requirements for the Bulletin server.

Recommended version of OAP is 7.x

 

Item
Description
OS
RHEL or CentOS 6 or higher (x86 or x64)
Software
To be installed by the Provider:
  • OS only
  • Apache server (PHP 5.3.3 or above)
CPU
2 core (3GHz or higher)
RAM
Minimum 2GB (recommended 8GB)
Disks
The disk storage space must be sufficient for storing all users’ data
Runtime Library
Version 2.2-235 (Odin Service Automation 7.0) From: https://doc.apsstandard.org/7.0/downloads/
NICs
Set-up with separated card (Frontnet, Backnet)
Postfix
Postfix must be setup to send emails (inet_protocols = ipv4)


 

Deployment Procedure

  • Log into SSH using Endpoint server
  • Go to /var/www/html folder and Copy the application package into it.
  • Download endpoint.sh, extract the archive from http://kb.parallels.com/Attachments/27241/Attachments/endpoint.tar. Place the file in the /var/www/html folder.
  • Open the terminal window and change the path to /var/www/html by executing the command cd /var/www/html
  • Generate the endpoint using the command

sh endpoint.sh <folder_name> <package_zip_file_name>

For example: sh endpoint.sh Bulletin Bulletin1.0-1.app.zip

  • This will create the new folder in the document root of the Apache server. The path will be /var/www/html/<folder_name>. In addition, all provisioning scripts will be copied to the particular folder and the necessary settings for endpoint URL redirection will be updated.
  • Endpoint                would               be               generated               in               the format http://<endpoint_domain_name>/<folder_name>.
  • Copy the generated endpoint API URL and paste it in OSA control panel while creating instance.


Importing Bulletin APS Package

  • To Import Bulletin APS Package:
  • In the OSA control panel, go to Top > Services > Applications. The list of the applications appears.



  • Click Import Package button.
  • There are two options for importing an Application Package:
    • To import the application package from the URL, select the URL option and specify the URL of the package location
    • Import the application from the local workstation, select the local file option, and specify the path to the application file using Choose File button.

  • Select the Enabled (available in subscriptions) checkbox.
  • Click Submit button.


Creating an Instance of Application

For Customers to be able to use a multi-tenant application, you need to create an instance of the application.

To create the instance of the application, use the following instructions:

  • In OSA Control Panel, go to Services > Applications > APS Packages. The list of the imported Application Packages appears.
  • Click Bulletin and the General tab of the application appear.
  • Click Add Instance button.



  • Type                  the                  deployed                  application's                  endpoint (example: http://<endpoint_domain_name>/<folder_name>) into the Application API end-point URI field and click Next button.


  • Enter Bulletin API Credentials, select the check box to enable logging and click Next button.

  • Verify the provisioning parameters and click Finish button.
  • Click on the instance created.
  • Select Edit button to edit Bulletin API Settings.



Note: If logging is enabled and log file folder and log file name fields are empty then application will assign default values as ‘aps_bulletin_log’ to both fields internally.


Creating Email Template

  • Go to Email Template tab.
  • Click Create button.


  • Fill in the fields for email template.



  • Click Save Changes button.

Note: Email template value will be stored in text file. This email template will be used in Welcome email sent upon the creation of Bulletin user.


Creating Bulletin Plans

  • Go to Plans tab.


  • Click Create button to create plans.
  • Provide the Plan Name (SMS limit) and Plan Code as shown in the screenshot below. SMS limit and plan code must be unique integer values.

  • Click Save button.
  • Repeat the steps from 2-4 to create another plan depending on provider’s requirements (E.g. create next plan for SMS limit 200 - plan code 2, for SMS limit 500 - plan code 3).


SMS Usage Report

To view SMS usage report:

  • Go to SMS Usage Report tab.
  • This will show the SMS Usage report of all the users who have subscribed to Bulletin APS service plans.




Configuring Services for Selling - POA

Creating Resource Types

Creating Resource Types on Basis of ‘Application Service Reference' Resource Class


As described in the Introduction section, it is necessary to create resource types based on the 'Application Service Reference' Resource Class.


The Application Service Reference Resource Class references the Global application configuration defined in the "Application" APS Type.


Note: This resource type provides a reference only to an installed application instance or service instances.


To create the required resource types on basis of the Application Service Reference Resource Class, proceed as follows:

  • Go to Services > Applications > APS Packages. The list of Applications opens.
  • Click Bulletin application. The General tab opens.
  • Open the Resource Types tab and click the Create button. The list of Resource Classes opens.

  • Click the Application Service Reference Resource Class.

  • Type the name of the resource type you will easily search later into the Name field.

  • Click the Next button. The list of implemented APS Types opens.
  • Click API Credentials in the list.

  • Click on the instance of the resource.

  • Check resource type parameters and click Finish button.
  • Repeat the steps 3-9 to create resource type “Bulletin_emailtemplate”.

  • Select Email Template as APS Type.

  • Click the instance of the resource.
  • Check resource type parameters and click the Finish button.


Creating Resource Types on Basis of ‘Application Counter (unit)’ Resource Class


You also need to create a Resource Type based on the Application Counter Resource Class.

Go to Services > Applications >APS Packages. The list of Applications opens.

  • Click Bulletin application. The General tab opens.
  • Open the Resource Types tab and click the Create button. The list of Resource Classes opens.

  • Click the Application Counter (unit) Resource Class.

  • Type the name of the resource type you will easily search later into the Name field.

  • Click Next button. The list of implemented application counter types opens.
  • Click SMS Usage in the list.

  • Check resource type parameters and click the Finish button.
  • Repeat the steps 2-7 to create Bulletin_plan_id resource type by selecting Plan ID resource.



Creating Resource Types on Basis of ‘Application Service' Resource Class


To create the required resource types on basis of the Application Service Resource Class, use the following instructions:

  • Go to Services > Applications > APS Packages. The list of Applications opens.
  • Click Bulletin application. The General tab opens.




  • Open the Resource Types tab and click the Create button. The list of Resource Classes opens.


  • Click the Application Service Resource Class.
  • Type the name of the resource type you will easily search later in the Name field and click

Next button.





  • The list of Application Services opens.
  • Click Company in the list.





  • Click Next button and specify additional parameters:
  • As this service is to be provisioned automatically, select Automatically provision service On from the drop-down menu.




  • Check the Resource Type parameters and click Finish button.




  • Repeat the steps 3-9 to create the resource type “Bulletin_users”.


  • Selecting User service from the list (Note: Do not select Automatically provision service On from the drop-down menu).




All the resources created are shown in the below screenshot.


Creating Service Template

Create a Service Template using the following instructions:

  • In OSA Control Panel, go to Products > Service Templates. The list of existing Service Templates opens.




  • Click Add New Service Template button.
  • Specify the general parameters of the Service Template:
  • Name - The name of the Service Template
  • Description - The description of the Service Template
  • Autoprovisioning – Select this, because a Subscription based on the Service Template should be auto-provisioned.
  • Type - Select the Custom value from the drop-down list.









  • Click Next button. The list of Resource Types opens. Select the created Resource Types.
  • Click Next button.




  • Check the parameters of the Service Template and click Finish button.

Note: Bulletin_emailtemplate resource type is not mandatory. If Bulletin_emailtemplate is not included in service template, then the application will not send an email upon the creation of a new user.


Configuring Services for Selling - PBA

Learn about how to configure the service plans that are necessary to form Bulletin APS subscriptions for sale.

Service Plans

To create a Service plan, open the Products > Service Plans submenu of the Navigation tree. The list of service plans available appears on the screen.

  • Click Add New Service Plan button.




  • Select Generic Service Plan.
  • Click Next button.









  • Fill the general details like Name, Service template, Description.
  • Select the service template by clicking on search option (magnifying glass).
  • Check Published checkbox.
  • Check Align Billing Order with Statement Day checkbox (this will align billing with calendar months).
  • Click Next button.


  • Select subscription period (E.g. 1 month or 1 year etc. based on provider’s choice) and price details.




  • Click Next button.
  • Setup the resource rate by clicking Setup Plan Rates button.






  • Select the resource “Bulletin_plan_id” and enter in Inc. Units field (should match the Plan code value of Plan Management). For example, the plan code is 1 for the sms limit 100; see below screenshot).

Note: Do not select Show in CP, Show in Store and Measurable option.

  • Click Finish button to complete the setup.
  • Repeat the steps 1-10 to create another service plan with another plan code.


Setting users resource rates

 

  • Open the created service plan.
  • Go to Resource Rates tab.
  • Click Add New Resource Rate button.
  • Check Bulletin_users and select Additional Resources from the dropdown menu.




  • Click Next button.
  • Fill in the Inc. Amount (this amount will be included in service plan don’t set this to unlimited)

and Max Amount.





  • Click Next button.

NOTE: User resource rate must have Show in CP option checked to be available for provisioning in CCP, it should be set this way by default but if not set it like in the image bellow


Setting upgrade/downgrade for service plans

 

  • Open the created service plan
  • Go to Upgrades tab.




  • Click Add New Allowed Upgrade/Downgrade button.
  • Select the plans you wish to upgrade/downgrade to.




  • Click Add Selected Plan(s) button.

Click Finish button to complete the setup.


Post-paid

Go to Services → Applications → Instances → Bulletin instance → Plans → Create.





Post-paid SMS Limit should be set to 0 for unlimited SMS. Create plan as described in picture above.





Create a service plan with the Inc. Amount (Plan Code) that you created for post-paid plan (in this case plan code Is 5). After post-paid service plan is created go to Resource rates tab and click on Add New Resource Rate button and add smsusage counter into service plan resource rates. Set Inc. Amount to 0 and Max. Amount to -1 (unlimited). Make sure you set Measurable to yes.

Click on resource rate.> click edit-> check Measurable -> click Save.


Price levels must be set for post-paid Service Plans as well:

  • Click on the service plans for which you would like to configure Resource Rates.
  • Go to Resource Rates tab.
  • Click the Bulletin_smsusage resource.
  • Click Edit Price Levels button.









  • In Overuse section click Add Levels and set usage with limits and prices for each level.




  • Click Save button.
  • It should now be possible to view the resource rate's tier.





Creating sales category

  • After creating the service plan go to Home > Products > Service Plans again.
  • Go to Sales Categories tab.
  • Click Add New Sales Category button.




  • Fill in the required fields.






  • Select Show in Customer Control Panel checkbox and click Finish button.
  • Click on the Sales category which you have created now.


  • Go to Service Plans tab.




  • Select the Plan(s) and click Add New Plan button.
  • Select the plans you wish to add and click Add Plan(s) To Category button.




Add the Sales Category to an existing Online Store Screen or create a new Screen by specifying its ID in the Category Id list of the Screen.


Bulletin Online Store

Open Products > Online Store
  • Click Add New Purchase Scenario button.




  • Enter Title, URL ID and select the Publish in Store checkbox to display in Online Store.


  • Click Save button.
  • Click on the created Purchase Scenario.
  • Click Add Existing Screen button.




  • Select Checkout_Screen and Hosting_Screen checkboxes and click Add Screen(s) button.




  • Click on Web Hosting.
  • Click Add Existing Category button.


  • Select “Bulletin” checkbox




  • Click Finish button.


Online Store Initial Setup

  • Open the Products > Online Store.
  • Click Connection Setup button.
  • Click Edit button.
  • The editing synchronization setting dialog window is displayed.
  • Type the online store node IP address (hostname) into the “Providers Store Host” field.
  • Click Save button to confirm changes.




  • Click Synchronize button.

Note: For more details on OBA online store installation and necessary port configuration refer to the following link: http://download.automation.odin.com/oa/7.1/oapremium/portal/en/billing_deployment/index

.htm?fileName=about.htm .


Synchronize

To synchronize the changes in Online Store, go to Products > Online Store then click Synchronize button.