3 +--------------------------------------------------------------------+
4 | Copyright CiviCRM LLC. All rights reserved. |
6 | This work is published under the GNU AGPLv3 license with some |
7 | permitted exceptions and without any warranty. For full license |
8 | and copyright information, see https://civicrm.org/licensing |
9 +--------------------------------------------------------------------+
13 * The Cxn API allows a Civi site to initiate a connection to a
14 * remote application. There are three primary actions:
16 * - register: Establish a new connection.
17 * - unregister: Destroy an existing connection.
18 * - get: Get a list of existing connections.
22 * Adjust metadata for "register" action.
27 function _civicrm_api3_cxn_register_spec(&$spec) {
28 $daoFields = CRM_Cxn_DAO_Cxn
::fields();
29 $spec['app_guid'] = $daoFields['app_guid'];
30 $spec['app_meta_url'] = [
31 'name' => 'app_meta_url',
32 'type' => CRM_Utils_Type
::T_STRING
,
33 'title' => ts('Application Metadata URL'),
34 'description' => 'Application Metadata URL',
36 'size' => CRM_Utils_Type
::HUGE
,
41 * Register with a remote application and create a new connection.
43 * One should generally identify an application using the app_guid.
44 * However, if you need to test a new/experimental application, then
45 * disable CIVICRM_CXN_CA and specify app_meta_url.
47 * @param array $params
49 * - app_guid: The unique identifer of the target application.
50 * - app_meta_url: The URL for the application's metadata.
54 function civicrm_api3_cxn_register($params) {
55 if (!empty($params['app_meta_url'])) {
56 list ($status, $json) = CRM_Utils_HttpClient
::singleton()->get($params['app_meta_url']);
57 if (CRM_Utils_HttpClient
::STATUS_OK
!= $status) {
58 throw new API_Exception("Failed to download appMeta. (Bad HTTP response)");
60 $appMeta = json_decode($json, TRUE);
61 if (empty($appMeta)) {
62 throw new API_Exception("Failed to download appMeta. (Malformed)");
65 elseif (!empty($params['app_guid'])) {
66 $appMeta = civicrm_api3('CxnApp', 'getsingle', [
67 'appId' => $params['app_guid'],
71 if (empty($appMeta) ||
!is_array($appMeta)) {
72 throw new API_Exception("Missing expected parameter: app_guid");
74 \Civi\Cxn\Rpc\AppMeta
::validate($appMeta);
77 /** @var \Civi\Cxn\Rpc\RegistrationClient $client */
78 $client = \Civi
::service('cxn_reg_client');
79 list($cxnId, $result) = $client->register($appMeta);
80 CRM_Cxn_BAO_Cxn
::updateAppMeta($appMeta);
82 catch (Exception
$e) {
83 CRM_Cxn_BAO_Cxn
::updateAppMeta($appMeta);
91 * Adjust metadata for cxn unregister.
95 function _civicrm_api3_cxn_unregister_spec(&$spec) {
96 $daoFields = CRM_Cxn_DAO_Cxn
::fields();
97 $spec['cxn_guid'] = $daoFields['cxn_guid'];
98 $spec['app_guid'] = $daoFields['app_guid'];
101 'type' => CRM_Utils_Type
::T_BOOLEAN
,
102 'title' => ts('Force'),
103 'description' => 'Destroy connection even if the remote application is non-responsive.',
109 * Unregister with a remote application; destroy an existing connection.
111 * Specify app_guid XOR cxn_guid.
113 * @param array $params
120 function civicrm_api3_cxn_unregister($params) {
121 $cxnId = _civicrm_api3_cxn_parseCxnId($params);
122 $appMeta = CRM_Cxn_BAO_Cxn
::getAppMeta($cxnId);
124 /** @var \Civi\Cxn\Rpc\RegistrationClient $client */
125 $client = \Civi
::service('cxn_reg_client');
126 list($cxnId, $result) = $client->unregister($appMeta, CRM_Utils_Array
::value('force', $params, FALSE));
132 * @param array $params
133 * An array with cxn_guid and/or app_guid.
135 * The CxnId. (If not available, then an exception is thrown.)
137 * @throws API_Exception
139 function _civicrm_api3_cxn_parseCxnId($params) {
142 if (!empty($params['cxn_guid'])) {
143 $cxnId = $params['cxn_guid'];
145 elseif (!empty($params['app_guid'])) {
146 $cxnId = CRM_Core_DAO
::singleValueQuery('SELECT cxn_guid FROM civicrm_cxn WHERE app_guid = %1', [
147 1 => [$params['app_guid'], 'String'],
150 throw new API_Exception("The app_guid does not correspond to an active connection.");
154 throw new API_Exception('Missing required parameter: cxn_guid');
160 * Adjust metadata for cxn get action.
164 function _civicrm_api3_cxn_get_spec(&$spec) {
165 // Don't trust AJAX callers or other external code to modify, filter, or return the secret.
166 unset($spec['secret']);
170 * Returns an array of Cxn records.
172 * @param array $params
173 * Array of one or more valid property_name=>value pairs.
178 function civicrm_api3_cxn_get($params) {
179 // Don't trust AJAX callers or other external code to modify, filter, or return the secret.
180 unset($params['secret']);
182 $result = _civicrm_api3_basic_get(_civicrm_api3_get_BAO(__FUNCTION__
), $params);
183 if (is_array($result['values'])) {
184 foreach (array_keys($result['values']) as $i) {
185 if (!empty($result['values'][$i]['app_meta'])) {
186 $result['values'][$i]['app_meta'] = json_decode($result['values'][$i]['app_meta'], TRUE);
188 if (!empty($result['values'][$i]['perm'])) {
189 $result['values'][$i]['perm'] = json_decode($result['values'][$i]['perm'], TRUE);
191 // Don't trust AJAX callers or other external code to modify, filter, or return the secret.
192 unset($result['values'][$i]['secret']);
200 * Adjust metadata for "getlink" action.
205 function _civicrm_api3_cxn_getlink_spec(&$spec) {
206 $daoFields = CRM_Cxn_DAO_Cxn
::fields();
207 $spec['app_guid'] = $daoFields['app_guid'];
208 $spec['cxn_guid'] = $daoFields['cxn_guid'];
209 $spec['page_name'] = [
210 'name' => 'page_name',
211 'type' => CRM_Utils_Type
::T_STRING
,
212 'title' => ts('Page Type'),
213 'description' => 'The type of page (eg "settings")',
215 'size' => CRM_Utils_Type
::HUGE
,
216 'api.aliases' => ['page'],
222 * @param array $params
224 * - cxn_guid OR app_guid: string.
229 function civicrm_api3_cxn_getlink($params) {
230 $cxnId = _civicrm_api3_cxn_parseCxnId($params);
231 $appMeta = CRM_Cxn_BAO_Cxn
::getAppMeta($cxnId);
233 if (empty($params['page_name']) ||
!is_string($params['page_name'])) {
234 throw new API_Exception("Invalid page");
237 /** @var \Civi\Cxn\Rpc\RegistrationClient $client */
238 $client = \Civi
::service('cxn_reg_client');
239 return $client->call($appMeta, 'Cxn', 'getlink', [
240 'page' => $params['page_name'],
246 * @param array $params
250 function civicrm_api3_cxn_getcfg($params) {
252 'CIVICRM_CXN_CA' => defined('CIVICRM_CXN_CA') ? CIVICRM_CXN_CA
: NULL,
253 'CIVICRM_CXN_VIA' => defined('CIVICRM_CXN_VIA') ? CIVICRM_CXN_VIA
: NULL,
254 'CIVICRM_CXN_APPS_URL' => defined('CIVICRM_CXN_APPS_URL') ? CIVICRM_CXN_APPS_URL
: NULL,
255 'siteCallbackUrl' => CRM_Cxn_BAO_Cxn
::getSiteCallbackUrl(),
257 return civicrm_api3_create_success($result);
261 * Creates or modifies a Cxn row.
263 * @param array $params
265 * - id, cxn_guid OR app_guid: string.
266 * - is_active: boolean.
271 function civicrm_api3_cxn_create($params) {
276 if (!empty($params['id'])) {
277 $cxnId = $params['id'];
280 $cxnId = _civicrm_api3_cxn_parseCxnId($params);
283 // see if it's sth to update
284 if (isset($params['options']) ||
isset($params['is_active'])) {
286 $dao = new CRM_Cxn_DAO_Cxn();
290 if (isset($params['is_active'])) {
291 $dao->is_active
= (int) $params['is_active'];
293 if (isset($params['options'])) {
294 $dao->options
= $params['options'];
297 $result = $dao->save();
301 return civicrm_api3_create_success($result, $params, 'Cxn', 'create');
304 catch (Exception
$ex) {