Event Scripts


1. Overview
2. How it works
3. Details and event types
4. Keywords
5. Sample library


1. Overview

The Event Scripts are RODOPI's solution to automated account support. Most Internet servers today are running Unix and are configured by editing simple text files. To simplify and automate the task of managing accounts many ISP's have created a set of Unix shell scripts. All they need to do when an account has to be created or changed is run the right script and pass the right parameters to it. This is still handwork, which is subject to errors. And usually the same change needs to be entered in the billing software, which leads to more handwork and of course, more confusion and errors. To synchronize the data in the billing software and the server the changes need to be done only in one place. And this has to be the billing software because it is the system that keeps all the ISP's data organized. But with the large variety of servers and configurations it is almost impossible to make the billing software manage all kinds of Internet accounts. That's why RODOPI automates only the task of supplying the account information to the server and letting it do the actual account management. All an ISP needs to get automated account management with RODOPI is to plug the right scripts into it.

return to top

2. How it works

Whenever an account is added, deleted or changed, RODOPI logs the event. A procedure scans the log of account changes for triggered events and for each account that has not been processed yet RODOPI checks if any script has been associated with this type of account and the event that has occurred. If such script exists, RODOPI parses the script and replaces specific keywords with the account information. Then it sends executes the script depending of his type.

The script will be uploaded by FTP to specified location:

Address: ftp://rodopi:jY6pass@unix1.yourdomain.com/usr/rodopi/mkuser.sh

If your firewall denies active connections between RODOPI server and the location specified you should check the "Passive" checkbox and RODOPI will use passive FTP connection. For security reasons you may wish to escape some characters in the account information RODOPI will substitute in your event script (like quotes in a text used in Perl or shell script). RODOPI allows you to specify a list of characters you wish to escape and the prefix that should be used to do this. For example: in a Perl script you should escape quotes and backslashes in a text with a backslash.

When uploaded the files will be saved with unique number added at the end of the file name:

mkuser.sh_1998155160405453

The remote server is responsible for executing that script so the changes can take effect. This can be done by scheduling or running in background a simple script which scans the directory where RODOPI uploads the scripts, executes any existing script and then deletes it. An example is the rodopi.sh shell script (see the samples library).
The configuration scripts must be executed with root permissions. If someone from the outside has access to the directory where the scripts are uploaded, he can do anything to your server. That's why you should create an account for RODOPI and restrict the access to the upload directory only to this account. Since FTP is not a secure protocol, the RODOPI database server and the servers that receive the scripts should be on your local network.

The mail script is sent by SMTP to the specified destination. You can use such event script to configure servers like Netscape Mail Server (all the changes will occur when the server receives the e-mail message) or simply to notify a technical person for the change.

The event script will be saved to the specified directory. If the "Execute" checkbox is checked it will be execute with the credentials of the account used for running the RODOPI Procedures service.

Example:
Command file: d:\temp\makeuser.bat 

Will be saved like with unique number at the end of the file name before the extension added:

makeuser2000155163027756.bat

The SQL script consist of single line with an SQL command. The command will be executed on your RODOPI database with permissions your RODOPI interface has when connects to the database.

Example:
SQL Script: exec MyService_OnInsert '@New_UserName@'

The Remote SQL script is similar to the SQL script but if has a connection string used to connect to SQL database using ODBC and a body with a SQL batch which will be executed with permissions the connection has.

Example:
Connection String: Provider=SQLOLEDB;APP=RODOPI;DATABASE=YourDB;DRIVER={SQL Server};Network Address=DBhost;Network Library=dbmssocn;PWD=rodopi;SERVER=DBhost;UID=Rodopi;
Script:
exec MyService_OnInsert '@New_UserName@'

The LDAP script is based on LDIF(LDAP Data Interchange Format).
You can add, modify or delete an entry in the specified DS server. 

Example:
Address: ldap://yourdomain.com:1003
Script:
1. Add new entry to the DS
	dn: cn=@LastName@, ou=Customers, o=root
	changetype: add
	cn: @LastName@
	address: @Addrress@
	phone: @HomePhone@
	email: @Email@
	objectClass: someclass
2. Modify existing entry in the DS 
	dn: cn=@LastName@, ou=Customers, o=root
	changetype: modify
	email: @Email@
3. Delete existing entry from the DS 
	dn: cn=@LastName@, ou=Customers, o=root
	changetype: delete

The HTTP Post script will be POSTed to the specified location via HTTP. You can use it to POST a command to an CGI which can take appropriate actions. In the body of the script you should specify one or more name=value pairs each of them on separate row. The values substituted by RODOPI will be URL escaped and all pairs will be joined with '&' as delimiter before the script is send. To ensure security transmission of the data you can use https: protocol.

Example:
Address: http://www.mydomain.com/script/execute.cgi
Script:
Action=NewUser
Param1=@New_UserName@
Param2=@New_Password@
 

The XML script will be POSTed to the specified location via HTTP. In the body of the script you can insert a XML formatted command. RODOPI will send the script, retrieve response and parse it accordingly the DTD scheme for script responses (http://www.rodopi.com/scriptresponse.dtd ). The response will be used to change account information for the account who triggered the event. You can specify an item and the value and RODOPI will update or insert (depending on "insert" attribute) such item in the account with the specified value. You can also specify whether or not the changes should trigger a new event.

Example:
Address: http://www.mydomain.com/script/xmlagent.cgi
Script:
<?xml version="1.0" ?>
<request>
  <update name="@Old_UserName@">
    <password>@New_Password@</password>
  </update>
</request>

Response:
<?xml version="1.0" ?>
<scriptresponse>
  <status code="0">Success</status>
  <set log="N">
    <value_LPSTR item="Description" insert="N">Activated</value_LPSTR>
    <value_DECIMAL item="Lines">5</value_DECIMAL>
  </set>
</scriptresponse>

The above response will update an item with keyword "Description" and will insert new item "Lines" with value of 5. The changes will not trigger an updated event.

return to top

3. Details and event types

The events that can occur are:

Each event in RODOPI can be attached to some detail (service) and for this event you define event script.

For example: You may have for Dialin Account detail for event Inserted event script that will create dialin accounts on your Server, whenever customer subscribes for this service. Check our sample library of event scripts.

return to top

4. Keywords

To get the account information in your script you can use specific keywords which RODOPI will replace before it sends the script to the server. You can assign them to script variables in the beginning, like this:

$username = '@New_UserName@';

RODOPI supports keywords in four different ways:

1. Old value of selected Item will be assigned to token like this: @Old_ItemKeyword@ where ItemKeyword is Keyword assigned to the Item.

2. New value of selected Item will be assigned to token like this: @New_ItemKeyword@ where ItemKeyword is Keyword assigned to the Item.

3. Current value of selected Item will be assigned to token like this: @Cur_[DetailKeyword.]ItemKeyword@ where ItemKeyword is Keyword assigned to the Item. You can add a DetailKeyword in front of the ItemKeyword seprated by dot (.). Thus the value can be taken not form the detail where the event was triggered but form another detail in the same plan.

4. Some specific keywords may be used:

Keyword

Description

@PlanInfoId@

Customer's PlanInfoId

@PlanId@

Customer's PlanId

@ObjectID@

Object's ID

@DetailID@

Detail's ID

@RegNumber@

Customer's RegNumber

@FirstName@

Customer’s First Name 

@MiddleName@

Customer’s Middle Name

@LastName@

Customer’s Last Name

@Company@

Customer’s Company

@Address@

Customer’s Address

@City@

Customer’s City

@State@

Customer’s State

@Zip@

Customer’s Zip

@HomePhone@

Customer’s Home Phone

@BusinessPhone@

Customer’s Business Phone

@Fax@

Customer’s Fax

@Email@

Customer’s Email

@Country@

Customer’s Country

@Provider@

Provider ID for this Plan (0 for all Plans not linked with specific Provider)

@GUID@

Global unique identifier

It lets you take different action based on the plan that the customer is subscribed for. The keyword @PlanInfoId@ is replaced with the identifier of the Plan Info which the account belongs to. The Plan Info identifiers are listed on the Plan Infos administration page.

If you want to use a '@' sign in you event scripts - write it twice. When script is executed it will be replaced with single '@' character.

return to top

5. Sample library

Here are all sample scripts that we currently supply to RODOPI customers. These scripts have been created and tested on specific systems. It is very likely that they won't work for you as they are. You will have to make the changes specific to your environment.

Unix

Process all uploaded scripts every 10 seconds

rodopi.sh

Add BSDI user

insert_BSDI_user.pl

Add FreeBSD user

insert_FreeBSD_user.pl

Add sendmail e-mail account

insert_sendmail.pl

Add Solaris user

insert_Solaris_user.pl

Delete Unix user

delete_user.pl

Delete Solaris user

delete_Solaris_user.pl

Add virtual domain to Apache web server

insert_apache.pl

Windows NT

Event scripts for NT Dialin accounts

Examples

Process all uploaded batch & cmd files every 10 seconds

rodopi.cmd
process.cmd
sleep.exe
rassapi.exe

MCIS 2.0 Mail Server

Email Management

documentation
download all scripts

IIS 4.0

Web Site Management

documentation
download all scripts

Radius Accounts

Radius Accounts Management

documentation
download all scripts


return to top