Commit | Line | Data |
---|---|---|
9d7974eb EM |
1 | <?php |
2 | /* | |
3 | +--------------------------------------------------------------------+ | |
4 | | Copyright CiviCRM LLC. All rights reserved. | | |
5 | | | | |
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 | +--------------------------------------------------------------------+ | |
10 | */ | |
11 | ||
12 | /** | |
13 | * | |
14 | * @package CRM | |
15 | * @copyright CiviCRM LLC https://civicrm.org/licensing | |
16 | */ | |
17 | ||
7b057b66 EM |
18 | use Civi\Api4\UserJob; |
19 | ||
9d7974eb EM |
20 | /** |
21 | * This class helps the forms within the import flow access submitted & parsed values. | |
22 | */ | |
23 | class CRM_Import_Forms extends CRM_Core_Form { | |
24 | ||
25 | /** | |
7b057b66 EM |
26 | * User job id. |
27 | * | |
28 | * This is the primary key of the civicrm_user_job table which is used to | |
29 | * track the import. | |
30 | * | |
31 | * @var int | |
32 | */ | |
33 | protected $userJobID; | |
34 | ||
35 | /** | |
36 | * @return int|null | |
37 | */ | |
38 | public function getUserJobID(): ?int { | |
39 | if (!$this->userJobID && $this->get('user_job_id')) { | |
40 | $this->userJobID = $this->get('user_job_id'); | |
41 | } | |
42 | return $this->userJobID; | |
43 | } | |
44 | ||
45 | /** | |
46 | * Set user job ID. | |
47 | * | |
48 | * @param int $userJobID | |
49 | */ | |
50 | public function setUserJobID(int $userJobID): void { | |
51 | $this->userJobID = $userJobID; | |
52 | // This set allows other forms in the flow ot use $this->get('user_job_id'). | |
53 | $this->set('user_job_id', $userJobID); | |
54 | } | |
55 | ||
56 | /** | |
57 | * User job details. | |
58 | * | |
59 | * This is the relevant row from civicrm_user_job. | |
60 | * | |
61 | * @var array | |
62 | */ | |
63 | protected $userJob; | |
64 | ||
65 | /** | |
66 | * Get User Job. | |
67 | * | |
68 | * API call to retrieve the userJob row. | |
69 | * | |
70 | * @return array | |
71 | * | |
72 | * @throws \API_Exception | |
73 | */ | |
74 | protected function getUserJob(): array { | |
75 | if (!$this->userJob) { | |
76 | $this->userJob = UserJob::get() | |
77 | ->addWhere('id', '=', $this->getUserJobID()) | |
78 | ->execute() | |
79 | ->first(); | |
80 | } | |
81 | return $this->userJob; | |
82 | } | |
83 | ||
84 | /** | |
85 | * Get submitted values stored in the user job. | |
86 | * | |
87 | * @return array | |
88 | * @throws \API_Exception | |
89 | */ | |
90 | protected function getUserJobSubmittedValues(): array { | |
91 | return $this->getUserJob()['metadata']['submitted_values']; | |
92 | } | |
93 | ||
94 | /** | |
95 | * Fields that may be submitted on any form in the flow. | |
96 | * | |
97 | * @var string[] | |
98 | */ | |
99 | protected $submittableFields = [ | |
100 | // Skip column header is actually a field that would be added from the | |
101 | // datasource - but currently only in contact, it is always there for | |
102 | // other imports, ditto uploadFile. | |
103 | 'skipColumnHeader' => 'DataSource', | |
104 | 'fieldSeparator' => 'DataSource', | |
105 | 'uploadFile' => 'DataSource', | |
106 | 'contactType' => 'DataSource', | |
dfa2f16c | 107 | 'contactSubType' => 'DataSource', |
7b057b66 EM |
108 | 'dateFormats' => 'DataSource', |
109 | 'savedMapping' => 'DataSource', | |
110 | 'dataSource' => 'DataSource', | |
dfa2f16c EM |
111 | 'dedupe_rule_id' => 'DataSource', |
112 | 'onDuplicate' => 'DataSource', | |
113 | 'disableUSPS' => 'DataSource', | |
9c16701f EM |
114 | 'doGeocodeAddress' => 'DataSource', |
115 | // Note we don't add the save mapping instructions for MapField here | |
116 | // (eg 'updateMapping') - as they really are an action for that form | |
117 | // rather than part of the mapping config. | |
118 | 'mapper' => 'MapField', | |
7b057b66 EM |
119 | ]; |
120 | ||
121 | /** | |
122 | * Get the submitted value, accessing it from whatever form in the flow it is | |
123 | * submitted on. | |
124 | * | |
9d7974eb EM |
125 | * @param string $fieldName |
126 | * | |
127 | * @return mixed|null | |
7b057b66 | 128 | * @throws \CRM_Core_Exception |
9d7974eb EM |
129 | */ |
130 | public function getSubmittedValue(string $fieldName) { | |
7b057b66 EM |
131 | if ($fieldName === 'dataSource') { |
132 | // Hard-coded handling for DataSource as it affects the contents of | |
133 | // getSubmittableFields and can cause a loop. | |
134 | return $this->controller->exportValue('DataSource', 'dataSource'); | |
135 | } | |
136 | $mappedValues = $this->getSubmittableFields(); | |
9d7974eb EM |
137 | if (array_key_exists($fieldName, $mappedValues)) { |
138 | return $this->controller->exportValue($mappedValues[$fieldName], $fieldName); | |
139 | } | |
140 | return parent::getSubmittedValue($fieldName); | |
141 | ||
142 | } | |
143 | ||
7b057b66 EM |
144 | /** |
145 | * Get values submitted on any form in the multi-page import flow. | |
146 | * | |
147 | * @return array | |
148 | */ | |
149 | public function getSubmittedValues(): array { | |
150 | $values = []; | |
151 | foreach (array_keys($this->getSubmittableFields()) as $key) { | |
152 | $values[$key] = $this->getSubmittedValue($key); | |
153 | } | |
154 | return $values; | |
155 | } | |
156 | ||
39dc35d4 EM |
157 | /** |
158 | * Get the available datasource. | |
159 | * | |
160 | * Permission dependent, this will look like | |
161 | * [ | |
162 | * 'CRM_Import_DataSource_CSV' => 'Comma-Separated Values (CSV)', | |
163 | * 'CRM_Import_DataSource_SQL' => 'SQL Query', | |
164 | * ] | |
165 | * | |
166 | * The label is translated. | |
167 | * | |
168 | * @return array | |
169 | */ | |
170 | protected function getDataSources(): array { | |
171 | $dataSources = []; | |
172 | foreach (['CRM_Import_DataSource_SQL', 'CRM_Import_DataSource_CSV'] as $dataSourceClass) { | |
173 | $object = new $dataSourceClass(); | |
174 | if ($object->checkPermission()) { | |
175 | $dataSources[$dataSourceClass] = $object->getInfo()['title']; | |
176 | } | |
177 | } | |
178 | return $dataSources; | |
179 | } | |
180 | ||
d452dfe6 EM |
181 | /** |
182 | * Get the name of the datasource class. | |
183 | * | |
184 | * This function prioritises retrieving from GET and POST over 'submitted'. | |
185 | * The reason for this is the submitted array will hold the previous submissions | |
186 | * data until after buildForm is called. | |
187 | * | |
188 | * This is problematic in the forward->back flow & option changing flow. As in.... | |
189 | * | |
190 | * 1) Load DataSource form - initial default datasource is set to CSV and the | |
191 | * form is via ajax (this calls DataSourceConfig to get the data). | |
192 | * 2) User changes the source to SQL - the ajax updates the html but the | |
193 | * form was built with the expectation that the csv-specific fields would be | |
194 | * required. | |
195 | * 3) When the user submits Quickform calls preProcess and buildForm and THEN | |
196 | * retrieves the submitted values based on what has been added in buildForm. | |
197 | * Only the submitted values for fields added in buildForm are available - but | |
198 | * these have to be added BEFORE the submitted values are determined. Hence | |
199 | * we look in the POST or GET to get the updated value. | |
200 | * | |
201 | * Note that an imminent refactor will involve storing the values in the | |
202 | * civicrm_user_job table - this will hopefully help with a known (not new) | |
203 | * issue whereby the previously submitted values (eg. skipColumnHeader has | |
204 | * been checked or sql has been filled in) are not loaded via the ajax request. | |
205 | * | |
206 | * @return string|null | |
207 | * | |
208 | * @throws \CRM_Core_Exception | |
209 | */ | |
c2562331 | 210 | protected function getDataSourceClassName(): string { |
d452dfe6 EM |
211 | $className = CRM_Utils_Request::retrieveValue( |
212 | 'dataSource', | |
213 | 'String' | |
214 | ); | |
215 | if (!$className) { | |
216 | $className = $this->getSubmittedValue('dataSource'); | |
217 | } | |
218 | if (!$className) { | |
219 | $className = $this->getDefaultDataSource(); | |
220 | } | |
221 | if ($this->getDataSources()[$className]) { | |
222 | return $className; | |
223 | } | |
224 | throw new CRM_Core_Exception('Invalid data source'); | |
225 | } | |
226 | ||
227 | /** | |
228 | * Allow the datasource class to add fields. | |
229 | * | |
230 | * This is called as a snippet in DataSourceConfig and | |
231 | * also from DataSource::buildForm to add the fields such | |
232 | * that quick form picks them up. | |
233 | * | |
234 | * @throws \CRM_Core_Exception | |
235 | */ | |
236 | protected function buildDataSourceFields(): void { | |
7b057b66 EM |
237 | $dataSourceClass = $this->getDataSourceObject(); |
238 | if ($dataSourceClass) { | |
239 | $dataSourceClass->buildQuickForm($this); | |
240 | } | |
241 | } | |
242 | ||
243 | /** | |
244 | * Get the relevant datasource object. | |
245 | * | |
246 | * @return \CRM_Import_DataSource|null | |
247 | * | |
248 | * @throws \CRM_Core_Exception | |
249 | */ | |
250 | protected function getDataSourceObject(): ?CRM_Import_DataSource { | |
251 | $className = $this->getDataSourceClassName(); | |
252 | if ($className) { | |
253 | /* @var CRM_Import_DataSource $dataSource */ | |
254 | return new $className($this->getUserJobID()); | |
255 | } | |
256 | return NULL; | |
257 | } | |
258 | ||
259 | /** | |
260 | * Allow the datasource class to add fields. | |
261 | * | |
262 | * This is called as a snippet in DataSourceConfig and | |
263 | * also from DataSource::buildForm to add the fields such | |
264 | * that quick form picks them up. | |
265 | * | |
266 | * @throws \CRM_Core_Exception | |
267 | */ | |
268 | protected function getDataSourceFields(): array { | |
d452dfe6 EM |
269 | $className = $this->getDataSourceClassName(); |
270 | if ($className) { | |
7b057b66 | 271 | /* @var CRM_Import_DataSource $dataSourceClass */ |
d452dfe6 | 272 | $dataSourceClass = new $className(); |
7b057b66 | 273 | return $dataSourceClass->getSubmittableFields(); |
d452dfe6 | 274 | } |
7b057b66 | 275 | return []; |
d452dfe6 EM |
276 | } |
277 | ||
278 | /** | |
279 | * Get the default datasource. | |
280 | * | |
281 | * @return string | |
282 | */ | |
283 | protected function getDefaultDataSource(): string { | |
284 | return 'CRM_Import_DataSource_CSV'; | |
285 | } | |
286 | ||
7b057b66 EM |
287 | /** |
288 | * Get the fields that can be submitted in the Import form flow. | |
289 | * | |
290 | * These could be on any form in the flow & are accessed the same way from | |
291 | * all forms. | |
292 | * | |
293 | * @return string[] | |
294 | * @throws \CRM_Core_Exception | |
295 | */ | |
296 | protected function getSubmittableFields(): array { | |
297 | $dataSourceFields = array_fill_keys($this->getDataSourceFields(), 'DataSource'); | |
298 | return array_merge($this->submittableFields, $dataSourceFields); | |
299 | } | |
300 | ||
6e78138c EM |
301 | /** |
302 | * Get the contact type selected for the import (on the datasource form). | |
303 | * | |
304 | * @return string | |
305 | * e.g Individual, Organization, Household. | |
306 | * | |
307 | * @throws \CRM_Core_Exception | |
308 | */ | |
309 | protected function getContactType(): string { | |
310 | $contactTypeMapping = [ | |
311 | CRM_Import_Parser::CONTACT_INDIVIDUAL => 'Individual', | |
312 | CRM_Import_Parser::CONTACT_HOUSEHOLD => 'Household', | |
313 | CRM_Import_Parser::CONTACT_ORGANIZATION => 'Organization', | |
314 | ]; | |
315 | return $contactTypeMapping[$this->getSubmittedValue('contactType')]; | |
316 | } | |
317 | ||
7b057b66 EM |
318 | /** |
319 | * Create a user job to track the import. | |
320 | * | |
321 | * @return int | |
322 | * | |
323 | * @throws \API_Exception | |
324 | */ | |
325 | protected function createUserJob(): int { | |
326 | $id = UserJob::create(FALSE) | |
327 | ->setValues([ | |
328 | 'created_id' => CRM_Core_Session::getLoggedInContactID(), | |
329 | 'type_id:name' => 'contact_import', | |
330 | 'status_id:name' => 'draft', | |
331 | // This suggests the data could be cleaned up after this. | |
332 | 'expires_date' => '+ 1 week', | |
333 | 'metadata' => [ | |
334 | 'submitted_values' => $this->getSubmittedValues(), | |
335 | ], | |
336 | ]) | |
337 | ->execute() | |
338 | ->first()['id']; | |
339 | $this->setUserJobID($id); | |
340 | return $id; | |
341 | } | |
342 | ||
343 | /** | |
344 | * @param string $key | |
345 | * @param array $data | |
346 | * | |
347 | * @throws \API_Exception | |
348 | * @throws \Civi\API\Exception\UnauthorizedException | |
349 | */ | |
350 | protected function updateUserJobMetadata(string $key, array $data): void { | |
351 | $metaData = array_merge( | |
352 | $this->getUserJob()['metadata'], | |
353 | [$key => $data] | |
354 | ); | |
355 | UserJob::update(FALSE) | |
356 | ->addWhere('id', '=', $this->getUserJobID()) | |
357 | ->setValues(['metadata' => $metaData]) | |
358 | ->execute(); | |
359 | $this->userJob['metadata'] = $metaData; | |
360 | } | |
361 | ||
4a01628c EM |
362 | /** |
363 | * Get column headers for the datasource or empty array if none apply. | |
364 | * | |
365 | * This would be the first row of a csv or the fields in an sql query. | |
366 | * | |
367 | * If the csv does not have a header row it will be empty. | |
368 | * | |
369 | * @return array | |
370 | * | |
371 | * @throws \API_Exception | |
372 | * @throws \CRM_Core_Exception | |
373 | */ | |
374 | protected function getColumnHeaders(): array { | |
375 | return $this->getDataSourceObject()->getColumnHeaders(); | |
376 | } | |
377 | ||
378 | /** | |
379 | * Get the number of importable columns in the data source. | |
380 | * | |
381 | * @return int | |
382 | * | |
383 | * @throws \API_Exception | |
384 | * @throws \CRM_Core_Exception | |
385 | */ | |
386 | protected function getNumberOfColumns(): int { | |
387 | return $this->getDataSourceObject()->getNumberOfColumns(); | |
388 | } | |
389 | ||
390 | /** | |
391 | * Get x data rows from the datasource. | |
392 | * | |
393 | * At this stage we are fetching from what has been stored in the form | |
394 | * during `postProcess` on the DataSource form. | |
395 | * | |
396 | * In the future we will use the dataSource object, likely | |
397 | * supporting offset as well. | |
398 | * | |
399 | * @param int $limit | |
400 | * | |
401 | * @return array | |
402 | * | |
403 | * @throws \CRM_Core_Exception | |
404 | * @throws \API_Exception | |
405 | */ | |
406 | protected function getDataRows(int $limit): array { | |
407 | return $this->getDataSourceObject()->getRows($limit); | |
408 | } | |
409 | ||
9d7974eb | 410 | } |