wiki:control-panel/alternative-interfaces

Alternatives to using a web browser to access your Control Panel

The May First/People Link Members Control panel is typically accesed via the web using a web browser.

In addition, there are two alternative ways to access and modify data in the control panel: via an Application Programmers Interface (API) that is accessible via http POST calls that any member can make from a remote computer and via a command line program (only accessible to administrators via a shell on hay.mayfirst.org).

Both methods follow a common syntax. See below for details about using each method.

Common Syntax

Each call is an array of key/value paramters. Every call must include an action and an object.

Available actions are: insert, update, delete, and select

Available objects are: member, contact, unique_unix_group, hosting_order, item

The remaing values are the values you wish to set on the given object (e.g. member_friendly_name = 'May First/People Link', or list_name = 'outreach-group').

There are three ways to set these values:

  • set: set the given field to the given value
  • where: operate on a object matching the given field value
  • sub: lookup a foreign key and match on that value

For example, if you want to display all user account records in which the user_account_login field is set to 'jamie', you would pass:

  • action=select
  • object=item
  • where:service_id=1
  • where:user_account_login=jamie

User accounts (and all things represented as tabs in a hosting order) are considered to be objects of the type "item". When acting on items, the service_id is required. That integer represents the kind of item (service_id 1 represents a user account). If you want to see the service_id number of other items, it is embedded in the URL of the web interface when you click on a tab. Email addresses are 2, DNS records are 9, etc.

Finding the membership record for May First/People Link:

  • action=select
  • object=member
  • where:member_friendly_name="May First/People Link"

If you want to insert a new record, you can use the insert action. To create a new user account in the May First/People Link hosting order (which is hosting_order_id 1):

  • action=insert
  • object=item
  • set:service_id=1
  • set:hosting_order_id=1
  • set:user_account_login=jamie
  • set:user_account_password="secretPass0rd"

Updating a record uses the same parameters as the "insert" action, but you must also pass an item_id. For instance, to change a user's password:

  • action=update
  • object=item
  • where:item_id=54321
  • set:service_id=1
  • set:hosting_order_id=1
  • set:user_account_login=jamie
  • set:user_account_password="newPass0rd"

If you weren't sure what hosting_order_id to use (perhaps you are writing a script that first creates the hosting order so you don't know before hand what ID it will get), you can use the sub option:

  • action=insert
  • object=item
  • set:service_id=1
  • sub:hosting_order_identifier=mayfirst.org
  • set:user_account_login=jamie
  • set:user_account_password="secretPass0rd"

The sub option will lookup a hosting order with an identifier set to mayfirst.org and, if found, add a hosting_order_id parameter set to the hosting_order_id of the matching record.

Similarly, if you are adding a contact, you can do the same trick with the Member Friendly Name. The following two examples will have the same result, since May First/People Link's member_id is 1.

  • action=insert
  • object=contact
  • sub:member_friendly_name="May First/People Link"
  • set:contact_first_name=jamie
  • set:contact_last_name=jamie
  • set:contact_email={{{jamie@example.com}}}
  • set:contact_billing=y
  • action=insert
  • object=contact
  • set:member_id=1
  • set:contact_first_name=jamie
  • set:contact_last_name=jamie
  • set:contact_email={{{jamie@example.com}}}
  • set:contact_billing=y

Using the web accessible API

Please note: the web API is not intended to be exposed to anonymous users! Any web-accessible pages for manipulating the control panel via the API must be password protected. You are responsible for the items created by your username.

The extra parameters for authentication are:

  • user_name (set to the username with permission to access the control panel)
  • user_pass (set to the matching password)

To use the web accessible API you must pass two additional parameters: an api user name and password.

We strongly encourage you to create a user account specifically for your applications and only give this user the privileges it needs to create the items you need created (usually, for creating items, you just need to add it to the "Hosting Order Access" tab in your control panel).

You can write programs in any language you want. These examples happen to be written in PHP.

This example creates a user account with a corresponding email address.

$api_user = 'your-api-user';
$api_password = 'secretPass0rd';
$hosting_order_id = 432;
$url = 'https://members.mayfirst.org/cp/api.php';

$user_name = 'julio';
$user_pass = 'secret';
$email_address = 'julio@example.com';

function red_fetch($url, $data) {
  $ch = curl_init();
  curl_setopt($ch, CURLOPT_URL, $url);
  curl_setopt($ch, CURLOPT_POST, 1);
  curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
  return json_decode(curl_exec($ch));
}

$data = array(
  'action' => 'insert',
  'object' => 'item',
  'user_name' => $api_user',
  'user_pass' => $api_password,
  'set:service_id' => 1,
  'set:hosting_order_id' => $hosting_order_id,
  'set:user_account_login' => $user_name,
  'set:user_account_password' => $user_pass,
);

$ret = red_fetch($url, $data);

if($ret['is_error'] == 1) {
  // handle errors
} 

$data = array(
  'action' => 'insert',
  'object' => 'item',
  'set:service_id' => 2,
  'set:hosting_order_id' => $hosting_order_id,
  'set:email_address' => $email_address,
  'set:email_recipient' => $user_name,
);

$ret = red_fetch($url, $data);

if($ret['is_error'] == 1) {
  // handle errors
} 

Using the command line (red-cli)

The command line program is only accessible to administrators and can only be run from the command line on hay as www-data@hay.mayfirst.org.

The cli program is in: /usr/local/share/red/ui/sbin/red-cli

No username or password is needed to run red-cli.

Options are passed via double-dash prefixed argument, e.g.:

red-cli --action select --object hosting_order --where:hosting_order_identifier mayfirst.org

Optionally, you can use the following syntax:

red-cli --action=select --object=hosting_order --where:hosting_order_identifier=mayfirst.org

In order to insert an item, the syntax is a little confusing. Here's what inserting a user and corresponding email looks like:

./red-cli --action=insert --object=item 
--set:hosting_order_id=THE_HOSTING_ORDER_NUMBER 
--set:service_id=1 --set:user_account_login=test42 
--set:user_account_password=test4242 
--where:hosting_order_identifier=THE_HOSTING_ORDER_DOMAIN.org;                                                                                      

./red-cli --action=insert --object=item 
--set:hosting_order_id=THE_HOSTING_ORDER_NUMBER 
--set:service_id=2 --set:email_address=test@THE_DOMAIN_NAME.org 
--set:email_address_recipient=test42 
--where:hosting_order_identifier=THE_HOSTING_ORDER_DOMAIN.org; 
Last modified 19 months ago Last modified on Feb 14, 2018, 2:58:54 PM