Changes between Initial Version and Version 1 of control-panel/alternative-interfaces

Timestamp:

Feb 7, 2012, 7:03:10 AM (12 years ago)

Author:

Jamie McClelland

Comment:

--

control-panel/alternative-interfaces

@@ +1 @@
+= Alternatives to using a web browser to access your Control Panel =
+
+The May First/People Link [https://members.mayfirst.org/cp 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"
+
+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 ==
+
+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';
+
+$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',
+  '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.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
+}}}
+
+