modules/netforum_authentication/API.txt

For extending, there are three hook functions:

hook_netforum_auth_categories() / hook_netforum_auth_od_categories()
hook_netforum_auth_user_categories($cst_key, &$apply_results)
hook_netforum_auth_user_fields()

The first returns an array of unique keys and descriptions and
the second takes a customer key and returns keys that correspond
to hook_netforum_auth_categories() keys that the customer is
qualified to be in.  The third function returns a list of fields to be included
with the user data.

hook_netforum_auth_user_fields() is called when loading a user, and any changes
to the data are stored locally.  The function should return an array of fields
in the Customer object, but beware that depending on how netforum is set up some 
fields may have no data and may cause the query to return zero records.  Safest to stick
to fields that start with cst_ - but test anything you want before implementing.  Here's an
example:

function utc_custom_netforum_auth_user_fields() {
  return array('cst_pref_comm_meth', 'cst_name_cp', 'badfield', 'adr_line1', 'cst_phn_number_complete_dn' );
}

Note that since the results are checked against the customer object, badfield is not included in the request

hook_netforum_auth_categories() is called at admin/user/netforum-roles
and provides the list of available categories for mapping netFORUM users
into drupal site roles.

hook_netforum_auth_user_categories() is called whenever a customer logs
in.  Any modules that implement this must also call netforum_auth_fresh_user_categories(true)
if the xWeb request was successful.  This is to keep the netFORUM 
Authentication module from confusing no results with no response from xWeb.
If you forget to call that function, then no roles will be applied to the user

Note that the keys don't have to be netFORUM keys as long as they are unique.

By default the netFORUM Authentication module will set roles based on membership types,
but here is an example that assigns role based on the customer add date or customer type:


function client_custom_netforum_auth_categories() {
  return array('before2007' => 'Customer added before January 1st, 2007',
      'after2007' => 'Customer added on or after January 1st, 2007',
      'individuals' => 'Individual customers (instead of organizations)', );
}

function client_custom_netforum_auth_user_categories($account) {
  //just in case we want to put them into more than one group
  $results = array();
  
  if ($account->cst_type == 'Organization') {
    $query_params = array(
      'szObjectName' => 'Organization',
      'szColumnList' => 'org_add_date',
      'szWhereClause' => "org_cst_key = '". $account->cst_key ."'",
      'szOrderBy' => '',
    );
    
    $response = netforum_xweb_request("GetQuery", $query_params);
    if (isset($response) AND $response->attributes()->recordReturn > 0 ) {
    
      // This is important!  This says that the results are valid and should be applied to the user,
      // if this is not set they are not applied at all, which keeps users from being kicked out of roles
      // if netforum isn't available.
      netforum_auth_fresh_user_categories(true);
      
      $org = $response->OrganizationObject; //If there were more than one of these, it would be plural.  Check the xweb test to see
      if (strtotime($org->org_add_date) >= strtotime("January 1st, 2007")) {
        $results[] = 'after2007';
      }
      else {
        $results[] = 'before2007';
      }
    }
  }
  else {
  
    $results[] = 'individuals'; //append to the results array.  Notice this corresponds to one of the keys from client_custom_netforum_auth_categories
    
    $query_params = array(
      'szObjectName' => 'Individual',
      'szColumnList' => 'ind_add_date',
      'szWhereClause' => "ind_cst_key = '". $account->cst_key ."'",
      'szOrderBy' => '',
    );
    
    $response = netforum_xweb_request("GetQuery", $query_params);
    if (isset($response) AND $response->attributes()->recordReturn > 0 ) {
    
      // This is important!  This says that the results are valid and should be applied to the user,
      // if this is not set they are not applied at all, which keeps users from being kicked out of roles
      // if netforum isn't available.
      netforum_auth_fresh_user_categories(true);
      
      $ind = $response->IndividualObject;
      if (strtotime($ind->ind_add_date) >= strtotime("January 1st, 2007")) {
        $results[] = 'after2007';
      }
      else {
        $results[] = 'before2007';
      }
    }
  }
  
  /* 
    Note that in this example, the xWeb request depends on the $account->cst_type field which is either Organization or Individual.  It could be simplified to 
    either call a query like this:
        $query_params = array(
          'szObjectName' => 'Customer',
          'szColumnList' => 'cst_add_date',
          'szWhereClause' => "cst_key = '". $account->cst_key ."'",
          'szOrderBy' => '',
        );
    because both individuals and organizations will have a Customer entry.  
    
    We could also have done a bit more magic and made the request look like this:
        $query_params = array(
          'szObjectName' => $account->cst_type,
          'szColumnList' => 'ind_add_date',
          'szWhereClause' => "ind_cst_key = '". $account->cst_key ."'",
          'szOrderBy' => '',
        );
        $result_type = $account->cst_type ."Object";
        $cst = $response->{$result_type};
    Which would substitute in the customer type both for the request AND for fetching the object out of the results.
    
    I thought the split would make a better example though.
  */
  
  return $results;

}


1	For extending, there are three hook functions:
2
3	hook_netforum_auth_categories() / hook_netforum_auth_od_categories()
4	hook_netforum_auth_user_categories($cst_key, &$apply_results)
5	hook_netforum_auth_user_fields()
6
7	The first returns an array of unique keys and descriptions and
8	the second takes a customer key and returns keys that correspond
9	to hook_netforum_auth_categories() keys that the customer is
10	qualified to be in. The third function returns a list of fields to be included
11	with the user data.
12
13	hook_netforum_auth_user_fields() is called when loading a user, and any changes
14	to the data are stored locally. The function should return an array of fields
15	in the Customer object, but beware that depending on how netforum is set up some
16	fields may have no data and may cause the query to return zero records. Safest to stick
17	to fields that start with cst_ - but test anything you want before implementing. Here's an
18	example:
19
20	function utc_custom_netforum_auth_user_fields() {
21	return array('cst_pref_comm_meth', 'cst_name_cp', 'badfield', 'adr_line1', 'cst_phn_number_complete_dn' );
22	}
23
24	Note that since the results are checked against the customer object, badfield is not included in the request
25
26	hook_netforum_auth_categories() is called at admin/user/netforum-roles
27	and provides the list of available categories for mapping netFORUM users
28	into drupal site roles.
29
30	hook_netforum_auth_user_categories() is called whenever a customer logs
31	in. Any modules that implement this must also call netforum_auth_fresh_user_categories(true)
32	if the xWeb request was successful. This is to keep the netFORUM
33	Authentication module from confusing no results with no response from xWeb.
34	If you forget to call that function, then no roles will be applied to the user
35
36	Note that the keys don't have to be netFORUM keys as long as they are unique.
37
38	By default the netFORUM Authentication module will set roles based on membership types,
39	but here is an example that assigns role based on the customer add date or customer type:
40
41
42	function client_custom_netforum_auth_categories() {
43	return array('before2007' => 'Customer added before January 1st, 2007',
44	'after2007' => 'Customer added on or after January 1st, 2007',
45	'individuals' => 'Individual customers (instead of organizations)', );
46	}
47
48	function client_custom_netforum_auth_user_categories($account) {
49	//just in case we want to put them into more than one group
50	$results = array();
51
52	if ($account->cst_type == 'Organization') {
53	$query_params = array(
54	'szObjectName' => 'Organization',
55	'szColumnList' => 'org_add_date',
56	'szWhereClause' => "org_cst_key = '". $account->cst_key ."'",
57	'szOrderBy' => '',
58	);
59
60	$response = netforum_xweb_request("GetQuery", $query_params);
61	if (isset($response) AND $response->attributes()->recordReturn > 0 ) {
62
63	// This is important! This says that the results are valid and should be applied to the user,
64	// if this is not set they are not applied at all, which keeps users from being kicked out of roles
65	// if netforum isn't available.
66	netforum_auth_fresh_user_categories(true);
67
68	$org = $response->OrganizationObject; //If there were more than one of these, it would be plural. Check the xweb test to see
69	if (strtotime($org->org_add_date) >= strtotime("January 1st, 2007")) {
70	$results[] = 'after2007';
71	}
72	else {
73	$results[] = 'before2007';
74	}
75	}
76	}
77	else {
78
79	$results[] = 'individuals'; //append to the results array. Notice this corresponds to one of the keys from client_custom_netforum_auth_categories
80
81	$query_params = array(
82	'szObjectName' => 'Individual',
83	'szColumnList' => 'ind_add_date',
84	'szWhereClause' => "ind_cst_key = '". $account->cst_key ."'",
85	'szOrderBy' => '',
86	);
87
88	$response = netforum_xweb_request("GetQuery", $query_params);
89	if (isset($response) AND $response->attributes()->recordReturn > 0 ) {
90
91	// This is important! This says that the results are valid and should be applied to the user,
92	// if this is not set they are not applied at all, which keeps users from being kicked out of roles
93	// if netforum isn't available.
94	netforum_auth_fresh_user_categories(true);
95
96	$ind = $response->IndividualObject;
97	if (strtotime($ind->ind_add_date) >= strtotime("January 1st, 2007")) {
98	$results[] = 'after2007';
99	}
100	else {
101	$results[] = 'before2007';
102	}
103	}
104	}
105
106	/*
107	Note that in this example, the xWeb request depends on the $account->cst_type field which is either Organization or Individual. It could be simplified to
108	either call a query like this:
109	$query_params = array(
110	'szObjectName' => 'Customer',
111	'szColumnList' => 'cst_add_date',
112	'szWhereClause' => "cst_key = '". $account->cst_key ."'",
113	'szOrderBy' => '',
114	);
115	because both individuals and organizations will have a Customer entry.
116
117	We could also have done a bit more magic and made the request look like this:
118	$query_params = array(
119	'szObjectName' => $account->cst_type,
120	'szColumnList' => 'ind_add_date',
121	'szWhereClause' => "ind_cst_key = '". $account->cst_key ."'",
122	'szOrderBy' => '',
123	);
124	$result_type = $account->cst_type ."Object";
125	$cst = $response->{$result_type};
126	Which would substitute in the customer type both for the request AND for fetching the object out of the results.
127
128	I thought the split would make a better example though.
129	*/
130
131	return $results;
132
133	}
134
135
136