SOAP Interface
Installation
The SOAP functionality must be available for both communication partners of PHP. (–with-soap) Prepared functions for the client and the server are available for LIMBAS. The server functions can be found in ‘extra/soap/server.php’. For the client, you can use the complete ‘public’ directory as a template. All basic settings in ‘lib/config.lib’ can be customized.
Configuration
# Autentication
$LIM["username"] = "limbasusername";
$LIM["pass"] = "pass";
// absolute path to LIMBAS
$LIM["lmpath"] = "/usr/local/httpd/htdocs/limbas_2/dependent";
// Serveraddress to Limbas
$LIM["lim_server"] = "192.168.10.20";
// Server URL to LIMBAS
$LIM["lim_urlPath"] = "/limbas_2/dependent";
$LIM["lim_url"] = "http://" . $LIM["lim_server"] . "/" . $LIM["lim_urlPath"];
// session name
$LIM["session_name"] = "limbas_".rtrim(base64_encode($LIM["username"]),"=");
$LIM["session_soap_name"] = $LIM["session_name"];
// soap activ / inactiv
$LIM["use_soap"] = 1;
// cookie activ / inactiv
$LIM["use_cookie"] = 0;
// name of cacheCookie
$LIM["cookieCache_name"] = "cacheCookie";
// absolute path to public root
$LIM["cache_home"] = "/usr/local/limbas/htdocs/limbas_2/public/";
// absolute path to cookie file
$LIM["cookie_path"] = $LIM["cache_home"]."/cache/".$LIM["cookieCache_name"];
// relative path to file cache
$LIM["cacheFolder"] = "cache/";
// relative path to data cache
$LIM["dbFolder"] = "db";
// the number of the ram disk (should be set manually by admin
$LIM["ramDisk"] = 15;
// if true files are cached and downloaded from the cache when available
$LIM["cacheFile"] = false;
// if true files are cached and downloaded from the cache when available
$LIM["cacheQuery"] = false;
// Max size in MB for the cache
$LIM["cacheSizeLimit"] = 200;
// seconds without checking if a new version of the file exists
$LIM["cacheMinExpiration"] = 48 * 60 * 60;
// %
$LIM["cacheToFree"] = 20;
// for md5 encryption of url
$LIM["key"] = "PASWORD";
define("DEBUG",false);
Functions
call_client
call_client – Initializes the SOAP Request This function executes a request to the SOAP server and returns a result array.
mixed call_client ( Array $lmpar)
cache_call_client
cache_call_client – initializes the SOAP query and caches the content. This function executes a request to the SOAP server and returns a result array.
mixed cache_call_client ( Array $lmpar)
The functions call_client and cache_call_client can also be mixed in one call.
Parameter definition of $lmpar
The array $lmpar defines the parameter properties. Using [$lmpar[0]] .. [$lmpar[1]] with only one SOAP call, multiple requests can be transferred at once. A single request is defined by [$lmpar[0]].
General
Use real table and field names instead of IDs (applies globally)
["use_noids"] = boolean $use_noids
Parameters for the return of Environment Variables from LIMBAS.
["getvars"] = array('fresult'[,'gtab'][,'gfield'][,'umgvar'][,'gselect'][,'userdat'][,'groupdat'][,'gmimetypes'][,'greminder'][,'workflow']);
Parameters for the action to be carried out.
["action"] = ['gtab_erg']['explorer_main'];
$TABID of the required table
["gtabid"] = number $TABID;
Required fields in the table $TABID; Specification required!
[$TABID]["showfields"] = array($FIELDID,$FIELDID...)
Parameter for search criteria (see ‘search’)
[$TABID]["gsr"] = array($gsr)
Show number of hits: If no value is entered the LIMBAS default setting is taken.
[$TABID]["count"] = number $count
Show page: If no value is entered, the first page is displayed.
[$TABID]["res_next"] = number $page
Sort: If no value is entered, it is sorted according to the LIMBAS default setting.
[$gtabid]["order"] = Array ['$FIELDID,ASC']
Limitation of the field contents of the Text or Long field type Long content can be limited on the server side.
[$TABID]["fieldlimit"][$FIELDID] = number $digits
Thumbnail generation of images of the upload field type. Images can be reduced on the server side.
[$TABID]["thumbsize"][$FIELDID] = mixed [$width] [$width x $height] [$width x] [x $height]
Convert all applicable characters to HTML entities
[$TABID]["noencode"] = 1
Examples
Example 1:
fresult: This example returns a result array of the table with the ID 1 and the fields with the ID’s [1,2,3,4,5,6]. Page [2] is displayed with max. 15 hits, sorted by field ID 2 ascending and by field ID 3 descending.
$lmpar["use_noids"] = 0;
$lmpar[0]["getvars"] = array('fresult');
$lmpar[0]["action"] = "gtab_erg";
$lmpar[0]["gtabid"] = "1";
$lmpar[0][1]["order"][0] = "2,ASC";
$lmpar[0][1]["order"][1] = "3,DESC";
$lmpar[0][1]["showfields"] = array(1,2,3,4,5,6);
$lmpar[0][1]["res_next"] = 2;
$lmpar[0][1]["count"] = 15;
Example 2:
fresult with use_noids:This example returns a result array of the table named [‘CUSTOMERS’] and the fields [‘NAME’,’FIRST NAME’,’STREET’].
The IDs can be specified using the real tables or field names. The output is also using the real names instead of the IDs.
$lmpar["use_noids"] = 1;
$lmpar[0]["getvars"] = array('fresult');
$lmpar[0]["action"] = "gtab_erg";
$lmpar[0]["gtabid"] = "KUNDEN";
$lmpar[0]['KUNDEN']["showfields"] = array('NAME','VORNAME','STRASSE');
Example 3:
gresult:This example returns a simplified result array of the ID 1 table of all eligible fields.
The use of shortcuts or use_noids is not possible.
$lmpar[0]["getvars"] = array('gresult');
$lmpar[0]["action"] = "gtab_erg";
$lmpar[0]["gtabid"] = "1";
Search
Find Tables
Search criteria are defined by the parameter [“gsr”].
A maximum of as many and / or searches can be placed over a field as specified in the $umgvar [“searchcount”].
["gsr"][$TABID][$FIELDID][$listid] = mixed $seachrvalue
$gsrres = $gsr[$gtabid][$key][$key1]; # searchvalue
$gsstxt = $gsr[$gtabid][$key]["txt"][$key1]; # text sensitive
$gssnum = $gsr[$gtabid][$key]["num"][$key1]; # numeric
$gsscs = $gsr[$gtabid][$key]["cs"][$key1]; # case sensitive
$gsandor = $gsr[$gtabid][$key]["andor"][$key1]; # and or
$gsstring = $gsr[$gtabid][$key]["string"][$key1]; # find all words
$gsneg = $gsr[$gtabid][$key]["neg"][$key1]; # negotiation
$gsr[$gtabid]['ID'] = ; # get record with specific ID
Examples
Example 1:
Returns all records of the Customers table (tabid 4) whose location (fieldid 5) is “Madrid”.
$gsr[4][5][0] = "Madrid";
$gsr[4][5]['txt'][0] = 1;
$lmpar["use_noids"] = 0;
$lmpar[0]["getvars"] = array('fresult');
$lmpar[0]["action"] = "gtab_erg";
$lmpar[0]["gsr"] = $gsr;
$lmpar[0]["gtabid"] = "4";
Example 2:
Returns all records of the table ‘Customers’ whose ‘location’ is “Madrid”.
$gsr['Kunden']['Ort'][0] = "Madrid";
$gsr['Kunden']['Ort']['txt'][0] = 1;
$lmpar["use_noids"] = 1;
$lmpar[0]["getvars"] = array('fresult');
$lmpar[0]["action"] = "gtab_erg";
$lmpar[0]["gsr"] = $gsr;
$lmpar[0]["gtabid"] = 'Kunden';
Example 3:
Returns the record of the table Customers (tabid 4) with ID 10.
$gsr[4]['ID'] = 10:
$lmpar[0]["getvars"] = array('fresult');
$lmpar[0]["action"] = "gtab_erg";
$lmpar[0]["gsr"] = $gsr;
$lmpar[0]["gtabid"] = "4";
Filter Reminder
Data sets that are provided with reminders can be filtered with additional search criteria:
- reminder : # Wiedervorlagen ID
- reminder_group : # Group assigned the reminder (group_id)
- reminder_user : # User to whom the reminder was assigned (user_id)
- reminder_create : # User who created the reminder (user_id | user_name)
- reminder_date : # Date of the reminder (date)
- reminder_from : # from date (date)
- reminder_to : # to date (date)
Example
$lmpart[$gtabid]["reminder"] = 2
$lmpart[$gtabid]["reminder_group"] = 4
$lmpart[$gtabid]["reminder_user"] = 1
$lmpart[$gtabid]["reminder_create"] = 1
$lmpart[$gtabid]["reminder_create"] = 'Meier'
$lmpart[$gtabid]["reminder_date"] = '01.01.2013'
$lmpart[$gtabid]["reminder_from"] = '>= 01.01.2013'
$lmpart[$gtabid]["reminder_to"] = '<= 15.01.2013'
Links
Recursive Result
The result array can be supplemented with contents of linked tables.
Where $VTABID is the table ID of the linked table. Multiple tables and recursive sublinks can be specified. Tables with links to themselves dissolve completely. The search parameter can also be applied to the linkage tables.
Returns the number of linked records:
[$VTABID]["showfields"] = array($FIELDID,$FIELDID);
Returns an array with the IDs of linked records:
$lmpar[0][$gtabid]["relationval"] = 1;
Example
This example returns a result array of the table with the ID 1 and the fields of the IDs [1,2,3,4,5,6] and a sub-array with the result of the linked table with the ID 2 and the fields of the IDs [1,2,3] back.
$lmpar["use_noids"] = 0;
$lmpar[0]["getvars"] = array('fresult');
$lmpar[0]["action"] = "gtab_erg";
$lmpar[0]["gtabid"] = "1";
$lmpar[0][1]["showfields"] = array(1,2,3,4,5,6);
$lmpar[0][2]["showfields"] = array(1,2,3);
Link Result
A table query can be filtered on existing links. For example, all correspondences of a specific person.
[$VTABID]["relation"]["gtabid"] = $GTABID;
[$VTABID]["relation"]["fieldid"] = $FIELDID;
[$VTABID]["relation"]["ID"] = $ID;
[$VTABID]["relation"]["type"] = [1][2];
Example
In this example, the order table should have the ID 1 and the customer table the ID 2. Customer is linked via the field with ID 10 to order.
Example 1:
This example returns a result array of the job table associated with the record ID 134 customer.
$lmpar[0]["gtabid"] = 1;
$lmpar[0][1]["relation"]["gtabid"] = 2;
$lmpar[0][1]["relation"]["fieldid"] = 10;
$lmpar[0][1]["relation"]["ID"] = 134;
$lmpar[0][1]["relation"]["type"] = 2;
Example 2:
This example returns a result array of the customer table associated with the record ID 20 order.
$lmpar[0]["gtabid"] = 2;
$lmpar[0][1]["relation"]["gtabid"] = 2;
$lmpar[0][1]["relation"]["fieldid"] = 10;
$lmpar[0][1]["relation"]["ID"] = 20;
$lmpar[0][1]["relation"]["type"] = 1;
Write
Data can also be written via the SOAP interface.
Create Record
["gnup"][$FIELDID] = mixed value
["gtabid"] = numeric $TABID;
["action"] = "gtab_new"
Example
Create a new record of the table with the table ID 1 and fill the fields with the field ID 3 and 4.
$lmpar[0]["gnup"][3] = "neuer"
$lmpar[0]["gnup"][4] = "Datensatz"
$lmpar[0]["gtabid"] = 1;
$lmpar[0]["action"] = "gtab_new";
For further actions, the return value “new_x” (new_0) is available on the server.
Archive/delete Record
["gtabid"] = numeric $TABID;
["action"] = "gtab_hide" | "gtab_delete"
["id"] = numeric $DATAID
Example
This example deletes the record with the ID 25 of the table with the table ID 1.
$lmpar[0]["gtabid"] = 1;
$lmpar[0]["action"] = "gtab_delete";
$lmpar[0]["id"] = 25;
Edit Record
["gup"][$TABID,$FIELDID,$DATID] = mixed value
["gtabid"] = numeric $TABID;
["action"] = "gtab_change"
Example
Here, 3 fields are changed with the field ID 3,4,5 of the table with the table ID 1 and the data record ID 25.
$lmpar[0]["gup"][1,3,25] = "hallo";
$lmpar[0]["gup"][1,4,25] = "ich";
$lmpar[0]["gup"][1,5,25] = "verstehs";
$lmpar[0]["gtabid"] = 1;
$lmpar[0]["action"] = "gtab_change";
Link Record / Delete Link
If one has the respective IDs of two data sets of different tables for which a link exists, these can be linked together. The link is defined by the field ID of the respective field. At least in one table, a field with the type “link” must be defined. The parameter “verkn_add_ID” creates a link; where “verkn_del_ID” deletes a link. Mind you, only the links, not the associated records.
["gnup"]["verknpf"][] = 1
["gnup"]["verkn_tabid"][] = numeric $TABID of source table
["gnup"]["verkn_fieldid"][] = numeric $FIELDID of source table
["gnup"]["verkn_ID"][] = numeric $DATID of source table
["gnup"]["verkn_add_ID"][] = numeric/Array) $DATID of destination table / create relation
["gnup"]["verkn_del_ID"][] = (numeric/Array) $DATID of destination table / drop relation
["gnup"]["verkn_linkParam"][] = array() # special params for extended fields; array("FIELDNAME_1"=>"CONTENT_1","FIELDNAME_2"=>"CONTENT_2")
["gtabid"] = numeric $TABID of source table
["action"] = "gtab_change"
Example A
For record ID 8 of the table Customer, a record ID 45 of the table Contact Person should be linked. Table customer has the TABID 5; There is a link to the contact person in the Customer table with the FIELDID 12 field.
["gnup"]["verknpf"][0] = 1
["gnup"]["verkn_tabid"][0] = 5
["gnup"]["verkn_fieldid"][0] = 12
["gnup"]["verkn_ID"][0] = 8
["gnup"]["verkn_add_ID"][0] = 45
["gtabid"] = 5
["action"] = "gtab_change"
Example B
You want to create a data record of the table Contact Person and at the same time link the record ID 8 with the customer. The table Contact Person has the TABID 6; There is a link or a back link to customer in the table Contact Person, which is defined by the field Customer with the FIELDID 10 of the table Contact Person. The assignment is made by the value ‘new’ of the parameters [“verkn_ID”] or [“verkn_add_ID”].
$lmpar[0]["gtabid"] = 6;
$lmpar[0]["action"] = "gtab_new";
$lmpar[0]["gnup"][2] = "Hans"
$lmpar[0]["gnup"][3] = "Meier"
$lmpar[0]["gnup"]["verknpf"][0] = 1
$lmpar[0]["gnup"]["verkn_tabid"][0] = 6
$lmpar[0]["gnup"]["verkn_fieldid"][0] = 10
$lmpar[0]["gnup"]["verkn_ID"][0] = 8
$lmpar[0]["gnup"]["verkn_add_ID"][0] = 'new'
Reminder
Search Reminder
Example
$lmpar[0]["action"] = 'reminder';
$lmpar[0]["getReminder"]['gtabid']; # tableid (int)
$lmpar[0]["getReminder"]['ID']; # dataset ID (int)
$lmpar[0]["getReminder"]['category']; # reminder category (int)
$lmpar[0]["getReminder"]['wfl_inst']; # workflow instance (int)
$lmpar[0]["getReminder"]['active']; # show reminders where become active after given date, if not set date is now() (date)
Create Reminder
Example
$lmpar[0]["action"] = "reminder"
$lmpar[0]["addReminder"]['to_user']; # destination user list as array (array)
$lmpar[0]["addReminder"]['to_group']; # destination group list as array (array)
$lmpar[0]["addReminder"]['date']; # when reminder becomes active (date)
$lmpar[0]["addReminder"]['gtabid']; # tableid (int)
$lmpar[0]["addReminder"]['ID']; # dataset ID (int)
$lmpar[0]["addReminder"]['category']; # reminder category (int)
$lmpar[0]["addReminder"]['wfl_inst']; # workflow instance (int)
$lmpar[0]["addReminder"]['content']; # short description
$lmpar[0]["addReminder"]['desc']; # long description
Delete Reminder
Beispiel
$lmpar[0]["action"] = "reminder"
$lmpar[0]["dropReminder"]['gtabid']; # tableid (int)
$lmpar[0]["dropReminder"]['ID']; # reminder ID, drop directly (int)
$lmpar[0]["dropReminder"]['category']; # reminder category (int)
$lmpar[0]["dropReminder"]['dat_id']; # dataset ID (int)
$lmpar[0]["dropReminder"]['wfl_inst']; # workflow instance (int)
$lmpar[0]["dropReminder"]['active']; # delete only reminders where become active after given date
$lmpar[0]["dropReminder"]['extension'] # special extension parameters (array)
Files
Content of field type “file upload”
If the uploaded table contains fields of type Upload, the result will be the metadata of the file.
Output example
[6] => Array
(
[id] => Array([0] => 2)
[name] => Array([0] => screene7.png)
[secname] => Array([0] => 2ca69e1e3a1e7)
[mimetype] => Array([0] => image/png)
[mimeid] => Array([0] => 196)
[perm] => Array([0] => 0)
[thumb_ok] => Array([0] => 1)
[0] => screene7.png
)
Simple File Upload
The simple file upload allows uploading a file to the “/tmp” directory of the server. This file can then be processed further. This file upload has nothing to do with the DMS functionality of Limbas. To load a file into the Limbas-DMS the corresponding DMS file upload function can be used.
The file content to be uploaded must be encoded with base64_encode. The name of the file is freely selectable.
The content of the files to be uploaded must be encoded with base64_encode. The names of the files are freely selectable.
Example
["action"] = "file_upload";
["file"]["content"][0] = base64_encode(file_get_contents('path/to/file'));
["file"]["file"][0] = 'SomeFileName';
DMS
File Query
The query of the DMS system works via the action “explorer_main”.
["action"] = "explorer_main"
["LID"] = numeric $folderID
["typ"] = numeric
["sub"] = boolean
["ffilter"] = array
Example
$lmpar[1]["getvars"] = array('fresult','filestruct');
# return result arrays, you can use (fresult,filestruct). fresult is needed for resultsets
$lmpar[1]["action"] = "explorer_main";
# you can use tables [gtab_erg] or filemanager [explorer_main]
$lmpar[1]['show_fields'] = array("19_16","19_25","19_19");
# IDs of requested fileds in tables, you can use files-table and meta-tables [tabid_field_id]
$lmpar[1]["LID"] = "2";
# ID of folder where searched
$lmpar[1]["typ"] = "1";
# type of filemanager, 1 = public directory, 2 = messages, 3 = tables, 4 = user directory, 5 = reports, 6 = dash, 7 = table relation; default = 1
$lmpar[1]["sub"] = "1";
# search in subfolders, 0 = no, 1 = yes; default = 0
$lmpar[1]["ffilter"]["viewmode"] = 1;
# viewmodus, 1 = normal, 2 = serachengine; default = 1
$lmpar[1]["ffilter"]["anzahl"] = 50;
# count of datasets seen in one page; default = [user_session]
$lmpar[1]["ffilter"]["page"] = 1;
# current page-number; default = 1
$lmpar[1]["ffilter"]["content_ao"] = 1;
# search and or, 1 = and, 2 = or; default = 1
$lmpar[1]["ffilter"]["content_cs"] = 0;
# search part of the word; default = 1
$lmpar[1]["verkn_ID"] = 0;
# Relation ID of linked table
Folder Structure
If requested via the parameter “getvars”, the folder structure is defined via the array “filestruct”. The folder structure is put out as a list. The value “level” defines the higher order. level “0” denotes the root directory.
Output Example
Output for folder with ID 4:
[view] => Array ([4] => 1)
[add] => Array ([4] => 1)
[addf] => Array ([4] => 1)
[del] => Array ([4] => 1)
[edit] => Array ([4] => 1)
[lock] => Array ([4] => 1)
[id] => Array ([4] => 4)
[name] => Array ([4] => Eigene Dateien)
[path] => Array ([4] => 0)
[level] => Array ([4] => 0)
[typ] => Array ( [4] => 4)
[fix] => Array ([4] => 1)
[readonly] => Array( [4] => 0)
[erstdatum] => Array ( [4] => 01.01.1970 01:00:01)
[editdatum] => Array ([4] => 01.01.1970 01:00:01)
[erstuser] => Array ([4] => 1)
[tab_id] => Array( [4] => 0)
[field_id] => Array ([4] => )
[tabid] => Array ([4] => 0)
Upload Files
Example
require("lib/include.lib");
function call_soap(){
$lmpar[1]["getvars"] = array('fresult');
$lmpar[1]["action"] = "explorer_main";
$lmpar[1]["LID"] = "58"; # ID of folder where the file shoud be uploaded
# you can upload more than one file at one time with the last array key
if($lmpar[1]["upload_file"]["content"][0] = base64_encode(file_get_contents("/mypath/test.jpg"))){ # you have to encode the filecontent to base64
$lmpar[1]["upload_file"]["name"][0] = "test.jpg"; # name of the file
$lmpar[1]["upload_file"]["mimetype"][0] = "image/jpeg"; # mimetype of file
$lmpar[1]["upload_file"]["dublicate"][0] = "overwrite"; # you can overwrite, rename, or versioning files
$lmpar[1]["upload_file"]["relation"][0] = null; #array("datid" => [datid], "gtabid" => [tableid], "fieldid" >= [fieldid]); # you can create a relation to a specific dataset
return call_client($lmpar);
}
}
$lmb = call_soap();
foreach($lmb[1]["ffile"]["id"] as $key => $value){
echo $lmb[1]["ffile"]["name"][$key].", ".$lmb[1]["ffile"]["mimetype"][$key]." - ";
}
Note: The relation is not a link via the FileManager, since this is the field type “file upload”.
Download Files
In order to retrieve the contents of a file, the detour via the LIMBAS proxy is necessary. All we need is the “ID” of the file, which is available through the output array. The “proxy.php” is part of the LIMBAS SOAP client. A URL to retrieve a file can be created as follows:
$url = base64_encode("main.php?action=download&ID=2");
$md5 = md5($LIM["key"].$url);
$url = proxy.php?key=$md5&url=$url
Direct Backend Access
If direct access to the LIMBAS backend is available, the simplified download call can be used:
$url = "main.php?action=download&ID=2";
In addition, images can be converted to thumbnails. For this we need another soap call parameter that describes the size of the thumbnail.
$lmpar[0][TABID]["thumbsize"][FIELDID]
As a result we get an additional link.
[link] => "URL TO THE FILE"
Upload files and link via advanced FileManager
To link an uploaded file directly to a record via the extendedFileManager, the following code has to be added in the example above (upload file):
$lmpar[0]["upload_file"]["link"]["verkn_tabid"][0] = $tabid; //target table
$lmpar[0]["upload_file"]["link"]["verkn_fieldid"][0] = $fieldid; //target field
$lmpar[0]["upload_file"]["link"]["verkn_ID"][0] = $datid; //target record
Extensions
The soap interface of LIMBAS can be supplemented with own extensions. These must be in one of the extension files named “ext_soap.inc”. The function has three optional parameters:
- $param_string = total parameter as string
- $param_array = Parameters separated by an array by “,”
- $lmb = current SOAP output array
The soap return is the return value of the function.
The call is done by:
$lmpar[0]["extension"][function] = params []
Example
$lmpar[0]["extension"]["myfunction"] = "hello world"
Extension Function
function myfunction($param_string=null,$param_array=null,$lmb=null){
return $param_string;
}
Another extension is the use of get_gresult (:::get_gresult()) over SOAP. It should be noted that the name of the function to be built consists of the prefix “extSoap” and the key. In this case “extSoap” + “myfunc1”. The function has two parameters:
- $val = Values to use for the SQL query
- $lmb = current SOAP output array.
Example
$fnkt['myfunc1'] = array('Kunden','2');
$lmpart[$gtabid]["extension"] = $fnkt
function extSoapmyfunc1($val,$lmb) {
$ext ['from'][0] = $val[0];
$ext ['where'][0] = "KundenNr" = $val[1];
return $ext;
}