View source for TCAdmin2 advanced module for WHMCS

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

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

== Download ==
The tcadmin2_advanced module can be downloaded from our [http://clients.tcadmin.com/downloads.php?action=displaycat&catid=5 client area].

== WHMCS module features ==
# Supports the following WHMCS module commands:
## Create: Create game and voice servers automatically. Game switching is supported.
## Suspend/Unsuspend/Terminate: Automatically suspend/enable/delete game and voice servers.
## Change Package: Update a game/voice servers private status, branding and slots. 
## Change Password: Change the client's TCAdmin password from within WHMCS.
# Direct client login from WHMCS to TCAdmin.
# 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 [[Configure Billing API|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-root/modules/servers/tcadmin2_advanced''' in your WHMCS installation.

=== Adding the TCAdmin Server ===
# Log in to WHMCS.
# Go to Configuration > Products/Services > Servers and Click on Add New Server.
# 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.

[[File: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:
<source lang="php">
<?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.
?>
</source>

=== 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:
<source lang="php">$billing_api_values["game_additional_slots"] = "ConfigOption:Extra Slots";</source>

==== 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:
<source lang="php">$billing_api_values["gamevar_VariableName"] = "ConfigOption:ReservedSlots";</source>

For voice servers:
<source lang="php">$billing_api_values["voicevar_VariableName"] = "CustomField:VoiceCodec";</source>

Minecraft example:
<source lang="php">$billing_api_values["gamevar_Xms"] = "2048";
$billing_api_values["gamevar_Xmx"] = "2048";</source>

==== 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.:
<source lang="php">
$billing_api_values["game_id_switch_1"]=10;
$billing_api_values["game_id_switch_2"]=20;
$billing_api_values["game_id_switch_3"]=30;
</source>

==== 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.
<source lang="php"><?php
  include('default_values.php');
  //Your code here
?></source>

===== Examples ===== 
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.

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

Don't start the game server after it has been created.
<source lang="php"><?php
  include('default_values.php');
  $billing_api_values["game_start"] = 0;
?></source>

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

<source lang="php"><?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;
}
?></source>

Set CPU priority to above normal.
<source lang="php"><?php
  include('default_values.php');
  //Valid values are: Idle BelowNormal Normal AboveNormal High RealTime
  $billing_api_values["game_priority"] = "AboveNormal";
?></source>

Set CPU and memory limits.
<source lang="php"><?php
  include('default_values.php');
  $billing_api_values["game_cpu"] = "75";
  $billing_api_values["game_memory"] = "2048";
?></source>

===== Minecraft Example =====

Create a configurable option named Ram with values 512MB, 1GB, 1.5GB. The values of slots, Xms and Xmx variables are set depending on its value. Create a config file in the tcadmin2_advanced folder named minecraft.php with these lines. In the product's module settings set the config file to minecraft.php.

<source lang="php">
<?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;
}
?></source>

==== Create a reseller package ====
* Create a reseller package in settings > reseller packages. In the list of reseller packages you can find the package id that you will need for the WHMCS configuration.

* create a file named reseller.php in the tcadmin2_advanced folder with these lines:

<source lang="php"><?php
  include('default_values.php');
  //Your code here
  $billing_api_values["role_id"]="3";
  $billing_api_values["package_id"]="12345";
?></source>

Change the value of role_id to the reseller role id (default reseller role id is 3)

Change the value of package_id to the id of the package you want to assign.

Select your reseller product in WHMCS. In the module settings tab set the config file to reseller.php

==== Other configuration parameters ====
; game_start / voice_start
: Start the service after it has been created. Allowed values are 1 and 0. The default value is 1.

; game_startup / voice_startup
: Specify the service's startup. Allowed values are Automatic, Manual, Disabled. The default value is Automatic.

; game_additional_slots / voice_additional_slots
: This value is added to game_slots. Default value is 0.

; game_priority / voice_priority
: Specify the CPU priority. Allowed values are Idle, BelowNormal, Normal, AboveNormal, High, RealTime. The default value is Normal.

; game_server / voice_server
: Specify the server id where the service will be created. You can use this parameter instead of specifying a value for game_datacenter.

; game_cpu / voice_cpu
: Specify a value from 1 to 100 (Windows) or 1 to (100 x number of processors) (Linux) See [[Limit_Service_CPU_and_Memory_Usage]]

; game_cpu / voice_cpu
: Specify a value from 1 to 100 or in the case of Linux 1 to (100 x number of processors) See [[Limit_Service_CPU_and_Memory_Usage]]

; game_memory / voice_memory
: Specify the max allowed memory in MB

; game_virtual_memory / game_virtual_memory
: Specify the max allowed virtual memory in MB (Windows only)

=== 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.
=== Cloudflare ===
If Cloudflare is blocking requests to the billing api go to the Cloudflare control panel > Web Application Firewall > Tools and allow your WHMCS IP.
[[File:WHMCS_WAF.png]]


[[File:WHMCS_WAF2.png]]

=== 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.'''
[[File: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.'''
[[File:WHMCSConfigurableOptions.png]]

* Enable upgrades for Configurable Options. This will allow the client to upgrade public/private slots and branding.
[[File:WHMCSUpgrades.png]]

* Configure the config file and game id.
* Map the custom fields and configurable options to a TCAdmin attribute.
[[File:WHMCSModuleSettings.png]]

* A preview of what the client will see in the order form.
[[File:WHMCSOrderForm.png]]