From a15f0bac02709e5ef8c8ca64f80120c1db9fecd6 Mon Sep 17 00:00:00 2001 From: "Jeroen van Meeuwen (Kolab Systems)" Date: Sun, 1 Apr 2012 13:58:46 +0100 Subject: Update documentation on Administration Panel --- .../en-US/Administration_Panel.xml | 718 ++++++++++++++++++++- 1 file changed, 709 insertions(+), 9 deletions(-) diff --git a/Architecture_and_Design/en-US/Administration_Panel.xml b/Architecture_and_Design/en-US/Administration_Panel.xml index 9c413df..c44aae9 100644 --- a/Architecture_and_Design/en-US/Administration_Panel.xml +++ b/Architecture_and_Design/en-US/Administration_Panel.xml @@ -192,7 +192,10 @@ In another rule-of-thumb we outline the naming convention for services and methods. - Service names consist of an object name either in singular or plural form. The singular form depicts actions are placed against a single instance of an object, such as object.add, whereas the plural form depicts actions are placed against multiple instances of an object, such as objects.list or objects.search. + Service names consist of an object name either in singular or plural form. The singular form depicts actions are placed against a single instance of an object, such as object.add, or at most one result entry is expected, such as object.find. + + + The plural form depicts actions that are placed against multiple instances of an object, such as objects.list or objects.search, or expect zero, one or more result entries to be returned. Method names often imply an action is placed against one or more objects in one request. Certain actions may be confusing though. For these we have the following rules; @@ -203,7 +206,7 @@ Finding an object - The method find is always executed against the service with the singular form of the object name. The target of calling a find method is to obtain exactly one instance of an object. The method should fail if the result set contains any number of objects not one. + The method find is always executed against the service with the singular form of the object name. The target of calling a find method is to obtain exactly zero or one instance of an object. The method should fail if the result set contains any number of objects not zero or one. @@ -246,6 +249,19 @@ + The reponse to a successful request that is expected to return a zero or one item, such as find methods, includes a result layout as follows: + + + +{ + "status": "OK", + "result": { + (... entry data ...) + } +} + + + The reponse to a successful request that is expected to return a list of zero, one or more items, such as list and search methods, includes a result layout as follows: @@ -282,7 +298,7 @@
<literal>domain.add</literal> Method - Depending on the technology used, quite the variety of things may need to happen when adding a domain to a Kolab Groupware deployment. + Depending on the technology used, quite the variety of things may need to happen when adding a domain to a Kolab Groupware deployment. This is therefore a responsbility for the API rather then the client. Parameters @@ -307,28 +323,88 @@ - + HTTP Method(s) POST, with an X-Session-Token HTTP/1.1 header. @@ -752,6 +828,343 @@ domain_dn="dc=${domain_dn}"
+
+ The <literal>form_value</literal> Service +
+ <literal>form_value.generate</literal> Method + + This API call allows access to routines that generate attribute values. It accepts data containing the names and values of other attribute values as input, which can be used to generate the new attribute value requested. + + + Parameters + + The form_value.generate API call accepts the following parameters: + + + + + + + + attribute + + The name of the attribute to generate the new value for. + + + + + + + + data + + An array with key => value pairs containing the attribute name (key) and attribute value (value) to use to generate the new value for the attribute supplied in . + + + + + This parameter is required for certain attributes, such as cn, but not for other attributes, such as userPassword. + + + + + + user_type_id + + An optional parameter to indicate to the API that the formation policy for users should be used. + + + + + Supply an integer indicating the user type to use policies for that user type. + + + Supply a boolean True to use a policy for users, allowing the use of policies not specific to any user type. + + + Supply a boolean False to reject the use of any user policy. + + + The default for this parameter is False. + + + + + + group_type_id + + An optional parameter to indicate to the API that the formation policy for groups should be used. + + + + + Supply an integer indicating the group type to use policies for that group type. + + + Supply a boolean True to use a policy for groups, allowing the use of policies not specific to any group type. + + + Supply a boolean False to reject the use of any group policy. + + + The default for this parameter is False. + + + + + + + + + + The API call does not allow both the user_type_id and group_type_id to; + + + + + + both be boolean False, + + + + + + both be boolean True, + + + + + + both be an integer reference to each respective type ID. + + + + + + + + + + + HTTP Method(s) + + POST, with an X-Session-Token HTTP/1.1 header. + + + + + Example Client Implementation + + A client could choose to have a user's password generated by the API. + + + + + Generate the User Password with the API + + +result = request('POST', 'form_value.generate_userpassword') +print result['userpassword'] + + + + + + + Response + + +{ + "status": "OK", + "result": { + "password": "3SQLAdcW_KZL5vO" + } + } + + + + + +
+ +
+ <literal>form_value.list_options</literal> Method + + para + + + Parameters + + params + + + + + HTTP Method(s) + + POST, with an X-Session-Token HTTP/1.1 header. + + + + + Example Client Implementation + + para + + + + + Response + + para + + + + +
+ +
+ <literal>form_value.validate</literal> Method + + para + + + This API call allows access to routines that generate attribute values. It accepts data containing the names and values of other attribute values as input, which can be used to generate the new attribute value requested. + + + Parameters + + The form_value.validate API call accepts the following parameters: + + + + + + + + attribute + + The name of the attribute to validate the value for. + + + + + + + + data + + The data to validate. + + + + + + + + user_type_id + + An optional parameter to indicate to the API that the validation policy for users should be used. + + + + + Supply an integer indicating the user type to use policies for that user type. + + + Supply a boolean True to use a policy for users, allowing the use of policies not specific to any user type. + + + Supply a boolean False to reject the use of any user policy. + + + The default for this parameter is False. + + + + + + group_type_id + + An optional parameter to indicate to the API that the validation policy for groups should be used. + + + + + Supply an integer indicating the group type to use policies for that group type. + + + Supply a boolean True to use a policy for groups, allowing the use of policies not specific to any group type. + + + Supply a boolean False to reject the use of any group policy. + + + The default for this parameter is False. + + + + + + + + + + The API call does not allow both the user_type_id and group_type_id to; + + + + + + both be boolean False, + + + + + + both be boolean True, + + + + + + both be an integer reference to each respective type ID. + + + + + + + + + + + HTTP Method(s) + + POST, with an X-Session-Token HTTP/1.1 header. + + + + + Example Client Implementation + + para + + + + + Response + + para + + + + +
+ + +
+
The <literal>group</literal> Service
@@ -1720,6 +2133,293 @@ if response_data.has_key('result'):
+
+ Storage Format for <literal>user_type</literal> + + The user types are backed by database entries, containing the following attributes per user type: + + + + + + <literal>id</literal> + + Of type INT, this attribute is automatically assigned by the database backend, unless specifically supplied on insert. + + + + + + + + <literal>key</literal> + + Of type VARCHAR(16), the key attribute is to hold a machine readable name. + + + + + + + + <literal>name</literal> + + Of type VARCHAR(128), the name attribute is to be the human-readable name for the user type. + + + + + + + + <literal>description</literal> + + Of type VARCHAR(256), the description attribute holds the description for the user type. + + + + + + + + <literal>attributes</literal> + + Of type TEXT, the attributes contains a serialized JSON object with the information needed for the API and client interface to build queries and forms for the user type. + + + + + + + + + +
+ The <literal>attributes</literal> Attribute Value Format + + The structure of the attributes attribute value is: + + +Array( + "<form_field_type>" => Array( + "<form_field_name>" => Array( + ['data' => Array( + "<form_field_name>"[, + "<form_field_name>"[, + "<form_field_name>"],] + ),] + ['type' => "text|select|multiselect|...",] + ['values' => Array( + "<value1>"[, + "<value1>"[, + "<value1>"],] + ),] + ) + ) + ) + + The attributes attribute to a user_type entry holds an array with any or all of the following <form_field_type> keys: + + + + + + <literal>auto_form_fields</literal> + + The auto_form_fields key holds an array of form fields that correspond with attributes for which the value is to be generated automatically, using an API call. + + + + + The key name for each key => value pair indicates the form field name for which the value is to be generated automatically. + + + Each array key corresponds with a user attribute name, and it's value is an array containing the name of the form fields for which the value to submit as part of the API call. + + + A User's <literal>displayname</literal> + + Provided the user type's auto_form_fields contains an array key of displayname, the array value for this key could look as follows: + + + +Array( + 'auto_form_fields' => Array( + 'displayname' => Array( + 'data' => Array( + 'givenname', + 'sn' + ), + ), + (...) + ), + (...) + ); + + + + This indicates to the client that a form field named 'displayname' is to be populated with the information contained within the form fields named 'givenname' and 'sn'. + + + If the client is capable of doing so, it should also update the form field named 'displayname' after the values for any of the form fields named 'givenname' or 'sn' have been changed. + + + + + With a JSON object payload containing the values of the form fields for which the names are contained within the 'data' key, if any, the client should submit a POST request on change of these form fields, and will be returned the new value for the automatically generated form field. + + + + + + <literal>form_fields</literal> + + The form_fields key holds an array of form fields that require user input. + + + + + The key name for each key => value pair indicates the form field name for which the value is to be supplied by the user. + + + Because some attributes can be multi-valued, or have a limited list of options, each defined form field in form_fields can hold an array with additional key => value pairs illustrating the type of form field that should be used, and what format to expect the result value in. + + + + Additional Information in <literal>form_fields</literal> + + + <literal>maxlength</literal> + + For a form field of type or type , this value holds the maximum length for a given item. + + + + + + + + <literal>type</literal> + + The type is to indicate the type of form field. Options include; + + + + + + + + <literal>text</literal> + + This is a regular input field of type text. + + + + + This is the default. + + + Additional parameters for a text form field include . + + + + + + <literal>list</literal> + + A form field of type list is expecting a list of text input values. + + + + + A client web interface could choose to display a textarea with the instructions to supply one item per line, or more advanced (better) equivalents, such as an add/delete widget. + + + A client command-line interface could choose to prompt for input values until an empty value is supplied. + + + Additional parameters for a list form field include , which holds the maximum length of each text value in the list. + + + + + + <literal>multiselect</literal> + + This form field is a select list, where multiple options may be selected (as opposed to a list, where only one option may be selected). + + + + + A client interface MUST consult the form_value.list_options API call for options, described in . + + + + + + <literal>select</literal> + + This form field is a selection list, of which one option may be selected. + + + + + A client interface MUST consult the form_value.list_options API call for options, described in . + + + + + + + + + + + + <literal>value_source</literal> + + para + + + + + + + + <literal>values</literal> + + para + + + + + + + + + + + + + + <literal>fields</literal> + + The fields key holds an array of form fields and values for said form fields, that are static. One example of such form fields is objectclass. + + + + + + + + + + +
+ + +
+
-- cgit v0.12