TCAdmin2 advanced module for WHMCS

From TCAdmin 2.0 Documentation

This software comes “as is” and no support for the module will be provided by TCAdmin. TCAdmin support is limited to the TCAdmin software.

Contents

Requirements

  1. You must have a fully installed, licensed and configured TCAdmin control panel. This includes game files, automation setup and email templates.
  2. Fully installed and configured WHMCS installation.
  3. PHP curl extension enabled.

Download

Tcadmin2_advanced can be downloaded from our client area.

WHMCS module features

  1. Supports the following WHMCS module commands:
    1. Create: Create game and voice servers automatically. Game switching is supported.
    2. Suspend/Unsuspend/Terminate: Automatically suspend/enable/delete game and voice servers.
    3. Change Package: Update a game/voice server’s private status, branding and slots.
    4. Change Password: Change the client’s TCAdmin password from within WHMCS.
  2. Direct client login from WHMCS to TCAdmin.
  3. Configurable options and custom fields can be used to set all the TCAdmin billing API attributes. This makes it flexible. You configure your packages exactly the way you want them. For example: Configure your packages to ask your clients for their game server’s location, hostname and passwords in the WHMCS order page.

TCAdmin billing API configuration settings

Configure TCAdmin according to the Billing API configuration page.

WHMCS Module Installation and Configuration

This software comes “as is” and no support for the module will be provided by TCAdmin. TCAdmin support is limited to the TCAdmin software.

Installing the Files

  • Extract the contents of the tcadmin2_advanced.zip file to the path /whmcs/modules/servers in your WHMCS installation.

Adding the TCAdmin Server

  1. Log in to WHMCS.
  2. Go to Configuration > Servers and Click on Add New Server.
  3. Enter the server name, hostname, ip address, port, select server type "tcadmin2_advanced" and enter the admin login and password that will be used. If you don’t use a hostname to access your control panel (cp.yourdomain.com:8880) enter your website’s ip address (xxx.xxx.xxx.xxx:8880) in the hostname field.

You have just installed and configured the TCAdmin module into WHMCS!

Creating Products in WHMCS

Create your product according to the WHMCS documentation. Configure with custom fields and configurable options to ask for location, hostname, slots, etc. http://docs.whmcs.com/Products_and_Services

Module settings

*** Why are your dropdowns empty? You need to configure your product with custom fields or configurable options for hostname, location, slots, etc. Then you will see them in the dropdowns. *** http://docs.whmcs.com/Products_and_Services

The most common attributes can be configured in the module settings tab. Other attributes can be configured in the file specified in the "Config File" field. The default config file is "default_values.php". You can use a config file that has different values depending on the configuration that is required for each product. Assign a "Custom Field" or "Configuration Option" from the list next to each attribute. When the module command is executed the tcadmin attribute will take the value of that field or option.

WHMCSModuleSettingsBlank.png

Config File
The file that contains the default values used for the TCAdmin billing API. This file contains more options not shown (commandline parameters, service level, game switching, etc). The default file is default_values.php
Game ID
The game id that will be created. If sent blank a game server will not be created.
Game Slots
The number of slots that the game server will have. If sent blank a game server will not be created. This value can also include the prefixes PRI and PUB to indicate a private or public game server. For example PRI8 will create a private server with 8 slots.
Game Private
1 if the game server is private. 0 if the game server is public. Default value is 0.
Game Branded
1 if the game server is branded. 0 if the game server is not branded. Default value is 0.
Game Datacenter
The datacenter id where the game server will be created. This is required if creating a game server.
Game Hostname
The game server's hostname. If the hostname is not specified it will be generated automatically. This is used only if the datacenter is specified.
Game RCon Password
The game server\'s RCon password. If the RCon password is not specified it will be generated automatically.
Game Private Password
The game server's private password. If the private password is not specified it will be generated automatically.
Voice ID
The voice id that will be created. To create a Teamspeak 2 virtual server the value must be TEAMSPEAK. To create a Teamspeak 3 virtual server the value must be TEAMSPEAK3. If sent blank a voice server will not be created. If the value sent is TEAMSPEAK3 you can also send values for upload and download quotas (voice_upload_quota and voice_download_quota)
Voice Slots
The number of slots that the voice server will have. If a valid voice id is sent and this value is sent blank it will use the value of game_slots. This value can also include the prefixes PRI and PUB to indicate a private or public game server. For example PRI8 will create a private server with 8 slots.
Voice Branded
1 if the voice server is private. 0 if the voice server is public. Default value is 0.
Voice Datacenter
The datacenter id where the voice server will be created. This is required if creating a game server.
Voice Hostname
The voice server's hostname. If the hostname is not specified it will be generated automatically.
Voice RCon Password
The voice server's RCon password. If the RCon password is not specified it will be generated automatically.
Voice Private Password
The voice server's private password. If the private password is not specified it will be generated automatically.
Reseller Packages
To create reseller packages leave all the game and voice information blank. Set the value of "Config File" to "reseller_values.php" and create the file in the tcadmin2_advanced folder with these lines:
<?php
  include('default_values.php');
 $billing_api_values["role_id"]="3"; //The reseller role id to assign to the user.
 $billing_api_values["package_id"]="1"; //The reseller package id to assign to the user.
?>

Advanced Configuration (Optional)

Config File (default_values.php)

To configure attributes that are not on the Module settings edit file default_values.php located in \whmcs\modules\servers\tcadmin2_advanced. You can configure them to take the value of a "Custom Field", "Configuration Option" or a fixed value.

  • To configure it to use a “Custom Field” set the value to "CustomField:FieldName" for example "CustomField:Hostname"
  • To configure it to use a "Configuration Option" set the value to "ConfigOption:OptionName " for example " ConfigOption:Slots"

Example:

$billing_api_values["game_additional_slots"] = "ConfigOption:Extra Slots";

Sending Custom Variable Values

You can specify custom variable values directly by using the following formats. The variable name is case sensitive. If custom variable values are not specified the default value will be used.

For game servers:

$billing_api_values["gamevar_VariableName"] = "ConfigOption:ReservedSlots";

For voice servers:

$billing_api_values["voicevar_VariableName"] = "CustomField:VoiceCodec";

Minecraft example:

$billing_api_values["gamevar_Xms"] = "2048";
$billing_api_values["gamevar_Xmx"] = "2048";

Sending Allowed Games for Game Switching

Use game_id_switch_# to specify the game ids that the service can be switched to. For example this allows the game server to switch to game ids 10, 20, 30.:

game_id_switch_1=10
game_id_switch_2=20
game_id_switch_3=30

Custom Config File

In some cases you might need to set different API values or execute custom code for a specific game. To use different config files for a game you can create a new text file with .php extension in the tcadmin2_advanced folder with these lines. Set the name of the custom file in your product's module settings.

<?php
  include('default_values.php');
  //Your code here
?>

The following example sets the game slots to a fixed value of 100. The Xmx and Xms variables are set to 2048 (2GB). All the other values configured in default_values.php are left the same. Upload to the tcadmin2_advanced folder. In the product's module settings configure this file as the config file instead of default_values.php.

<?php
  include('default_values.php');
  $billing_api_values["game_slots"] = 100;
  $billing_api_values["gamevar_Xms"] = "2048";
  $billing_api_values["gamevar_Xmx"] = "2048";
?>

Don't start the game server after it has been created.

<?php
  include('default_values.php');
  $billing_api_values["game_start"] = 0;
?>

The following example reads the value of a configurable option named Ram. The values of slots, Xms and Xmx variables are set depending on its value.

<?php
include('default_values.php');
switch ($params["configoptions"]["Ram"])
{
case "512MB":
  $billing_api_values["gamevar_Xms"] = "512";
  $billing_api_values["gamevar_Xmx"] = "512";
  $billing_api_values["game_slots"] = 12;
  break;
case "1GB":
  $billing_api_values["gamevar_Xms"] = "1024";
  $billing_api_values["gamevar_Xmx"] = "1024";
  $billing_api_values["game_slots"] = 20;
  break;
case "1.5GB":
  $billing_api_values["gamevar_Xms"] = "1512";
  $billing_api_values["gamevar_Xmx"] = "1512";
  $billing_api_values["game_slots"] = 35;
  break;
case "2GB":
  $billing_api_values["gamevar_Xms"] = "2048";
  $billing_api_values["gamevar_Xmx"] = "2048";
  $billing_api_values["game_slots"] = 40;
  break;
}
?>

The following example sends a different game id depending the location selected by the client. You must have a custom field named Location.

<?php
include('default_values.php');
switch ($params["customfields"]["Location"])
{
case "1":
  $billing_api_values["game_id"] = 11;
  break;
case "2":
  $billing_api_values["game_id"] = 12;
  break;
}
?>

Specifying Different Module Value and Display Value

In WHMCS, you can configure dropdowns and radios to send a different value to the module than the one that is displayed in the order form. This is useful because you must send ids to the TCAdmin billing api but you want to show a friendly name to the client. The module value and display value are separated by the pipe character "|". The format is ModuleValue|DisplayValue For example: You can create a dropdown list that has the locations New York and Dallas but you want the billing api to receive the datacenter ids 1 and 2. You can create a "Custom Field" of type "Drop Down" with these options: 1|Dallas,2|NewYork

Troubleshooting

  • The values sent to TCAdmin are saved in the log file /home/tcadmin/Logs/Web/BillingApi.LastCommand.log or C:\Program Files\TCAdmin2\Logs\Web\BillingApi.LastCommand.log Make sure TCAdmin is receiving the correct values. The values required to create a game server are: game_id, game_slots, game_datacenter.
  • If TCAdmin accepts the values a scheduled task is created. If the game server is never created go to System > General Settings > Scheduled Tasks. Select the Day view and click on the task that was created. You should see the error message preventing the game server from being created. Correct the problem and start the task again. You don't need to send the command from WHMCS again.

Update Products and Services from tcadmin to tcadmin2_advanced

If you are going to keep the same custom fields and configurable options in your products you need to follow these steps:

  • Update the module settings in the product. Switch from tcadmin to tcadmin2_advanced module and map the required tcadmin attributes to custom fields and configurable options.
  • Update the server field in the client's service.

If you are going to change custom fields and configurable options we recommend you create a copy of the product and modify the copy (Duplicate link at the top of the products page). When the new product is ready go to the client's service. Change the package and server. After you change the package all the values of custom fields and configurable options for that service will be lost and you will not be able to recover them. Enter the correct values again and save.

To enable direct client login from WHMCS to TCAdmin you must configure the service’s username and password. To disable this feature leave the username and password fields blank.

Example

The following screenshots show how to configure a product's order form so it asks for the location, hostname, rcon password, private password, number of slots, branded/not branded.

  • A drop down to capture the location.
  • A textbox to capture the hostname.
  • A textbox to capture the rcon password.
  • A textbox to capture the private password.
  • These are configured as custom fields because their values don't affect the product's pricing.

WHMCSCustomFields.png

  • A drop down to capture the number of slots.
  • A radio to ask if the game server will be branded or not.
  • These are configured as configurable options because pricing changes depending on the value selected by the client.

WHMCSConfigurableOptions.png

  • Enable upgrades for Configurable Options. This will allow the client to upgrade public/private slots and branding.

WHMCSUpgrades.png

  • Configure the config file and game id.
  • Map the custom fields and configurable options to a TCAdmin attribute.

WHMCSModuleSettings.png

  • A preview of what the client will see in the order form.

WHMCSOrderForm.png