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 +--------------------------------------------------------------------+
15 * @copyright CiviCRM LLC https://civicrm.org/licensing
18 use Civi\Api4\UserJob
;
21 * This class helps the forms within the import flow access submitted & parsed values.
23 class CRM_Import_Forms
extends CRM_Core_Form
{
28 * This is the primary key of the civicrm_user_job table which is used to
38 public function getUserJobID(): ?
int {
39 if (!$this->userJobID
&& $this->get('user_job_id')) {
40 $this->userJobID
= $this->get('user_job_id');
42 return $this->userJobID
;
48 * @param int $userJobID
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);
59 * This is the relevant row from civicrm_user_job.
68 * API call to retrieve the userJob row.
72 * @throws \API_Exception
74 protected function getUserJob(): array {
75 if (!$this->userJob
) {
76 $this->userJob
= UserJob
::get()
77 ->addWhere('id', '=', $this->getUserJobID())
81 return $this->userJob
;
85 * Get submitted values stored in the user job.
88 * @throws \API_Exception
90 protected function getUserJobSubmittedValues(): array {
91 return $this->getUserJob()['metadata']['submitted_values'];
95 * Fields that may be submitted on any form in the flow.
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',
107 'contactSubType' => 'DataSource',
108 'dateFormats' => 'DataSource',
109 'savedMapping' => 'DataSource',
110 'dataSource' => 'DataSource',
111 'dedupe_rule_id' => 'DataSource',
112 'onDuplicate' => 'DataSource',
113 'disableUSPS' => 'DataSource',
117 * Get the submitted value, accessing it from whatever form in the flow it is
120 * @param string $fieldName
123 * @throws \CRM_Core_Exception
125 public function getSubmittedValue(string $fieldName) {
126 if ($fieldName === 'dataSource') {
127 // Hard-coded handling for DataSource as it affects the contents of
128 // getSubmittableFields and can cause a loop.
129 return $this->controller
->exportValue('DataSource', 'dataSource');
131 $mappedValues = $this->getSubmittableFields();
132 if (array_key_exists($fieldName, $mappedValues)) {
133 return $this->controller
->exportValue($mappedValues[$fieldName], $fieldName);
135 return parent
::getSubmittedValue($fieldName);
140 * Get values submitted on any form in the multi-page import flow.
144 public function getSubmittedValues(): array {
146 foreach (array_keys($this->getSubmittableFields()) as $key) {
147 $values[$key] = $this->getSubmittedValue($key);
153 * Get the available datasource.
155 * Permission dependent, this will look like
157 * 'CRM_Import_DataSource_CSV' => 'Comma-Separated Values (CSV)',
158 * 'CRM_Import_DataSource_SQL' => 'SQL Query',
161 * The label is translated.
165 protected function getDataSources(): array {
167 foreach (['CRM_Import_DataSource_SQL', 'CRM_Import_DataSource_CSV'] as $dataSourceClass) {
168 $object = new $dataSourceClass();
169 if ($object->checkPermission()) {
170 $dataSources[$dataSourceClass] = $object->getInfo()['title'];
177 * Get the name of the datasource class.
179 * This function prioritises retrieving from GET and POST over 'submitted'.
180 * The reason for this is the submitted array will hold the previous submissions
181 * data until after buildForm is called.
183 * This is problematic in the forward->back flow & option changing flow. As in....
185 * 1) Load DataSource form - initial default datasource is set to CSV and the
186 * form is via ajax (this calls DataSourceConfig to get the data).
187 * 2) User changes the source to SQL - the ajax updates the html but the
188 * form was built with the expectation that the csv-specific fields would be
190 * 3) When the user submits Quickform calls preProcess and buildForm and THEN
191 * retrieves the submitted values based on what has been added in buildForm.
192 * Only the submitted values for fields added in buildForm are available - but
193 * these have to be added BEFORE the submitted values are determined. Hence
194 * we look in the POST or GET to get the updated value.
196 * Note that an imminent refactor will involve storing the values in the
197 * civicrm_user_job table - this will hopefully help with a known (not new)
198 * issue whereby the previously submitted values (eg. skipColumnHeader has
199 * been checked or sql has been filled in) are not loaded via the ajax request.
201 * @return string|null
203 * @throws \CRM_Core_Exception
205 protected function getDataSourceClassName(): string {
206 $className = CRM_Utils_Request
::retrieveValue(
211 $className = $this->getSubmittedValue('dataSource');
214 $className = $this->getDefaultDataSource();
216 if ($this->getDataSources()[$className]) {
219 throw new CRM_Core_Exception('Invalid data source');
223 * Allow the datasource class to add fields.
225 * This is called as a snippet in DataSourceConfig and
226 * also from DataSource::buildForm to add the fields such
227 * that quick form picks them up.
229 * @throws \CRM_Core_Exception
231 protected function buildDataSourceFields(): void
{
232 $dataSourceClass = $this->getDataSourceObject();
233 if ($dataSourceClass) {
234 $dataSourceClass->buildQuickForm($this);
239 * Get the relevant datasource object.
241 * @return \CRM_Import_DataSource|null
243 * @throws \CRM_Core_Exception
245 protected function getDataSourceObject(): ?CRM_Import_DataSource
{
246 $className = $this->getDataSourceClassName();
248 /* @var CRM_Import_DataSource $dataSource */
249 return new $className($this->getUserJobID());
255 * Allow the datasource class to add fields.
257 * This is called as a snippet in DataSourceConfig and
258 * also from DataSource::buildForm to add the fields such
259 * that quick form picks them up.
261 * @throws \CRM_Core_Exception
263 protected function getDataSourceFields(): array {
264 $className = $this->getDataSourceClassName();
266 /* @var CRM_Import_DataSource $dataSourceClass */
267 $dataSourceClass = new $className();
268 return $dataSourceClass->getSubmittableFields();
274 * Get the default datasource.
278 protected function getDefaultDataSource(): string {
279 return 'CRM_Import_DataSource_CSV';
283 * Get the fields that can be submitted in the Import form flow.
285 * These could be on any form in the flow & are accessed the same way from
289 * @throws \CRM_Core_Exception
291 protected function getSubmittableFields(): array {
292 $dataSourceFields = array_fill_keys($this->getDataSourceFields(), 'DataSource');
293 return array_merge($this->submittableFields
, $dataSourceFields);
297 * Get the contact type selected for the import (on the datasource form).
300 * e.g Individual, Organization, Household.
302 * @throws \CRM_Core_Exception
304 protected function getContactType(): string {
305 $contactTypeMapping = [
306 CRM_Import_Parser
::CONTACT_INDIVIDUAL
=> 'Individual',
307 CRM_Import_Parser
::CONTACT_HOUSEHOLD
=> 'Household',
308 CRM_Import_Parser
::CONTACT_ORGANIZATION
=> 'Organization',
310 return $contactTypeMapping[$this->getSubmittedValue('contactType')];
314 * Create a user job to track the import.
318 * @throws \API_Exception
320 protected function createUserJob(): int {
321 $id = UserJob
::create(FALSE)
323 'created_id' => CRM_Core_Session
::getLoggedInContactID(),
324 'type_id:name' => 'contact_import',
325 'status_id:name' => 'draft',
326 // This suggests the data could be cleaned up after this.
327 'expires_date' => '+ 1 week',
329 'submitted_values' => $this->getSubmittedValues(),
334 $this->setUserJobID($id);
342 * @throws \API_Exception
343 * @throws \Civi\API\Exception\UnauthorizedException
345 protected function updateUserJobMetadata(string $key, array $data): void
{
346 $metaData = array_merge(
347 $this->getUserJob()['metadata'],
350 UserJob
::update(FALSE)
351 ->addWhere('id', '=', $this->getUserJobID())
352 ->setValues(['metadata' => $metaData])
354 $this->userJob
['metadata'] = $metaData;
358 * Get column headers for the datasource or empty array if none apply.
360 * This would be the first row of a csv or the fields in an sql query.
362 * If the csv does not have a header row it will be empty.
366 * @throws \API_Exception
367 * @throws \CRM_Core_Exception
369 protected function getColumnHeaders(): array {
370 return $this->getDataSourceObject()->getColumnHeaders();
374 * Get the number of importable columns in the data source.
378 * @throws \API_Exception
379 * @throws \CRM_Core_Exception
381 protected function getNumberOfColumns(): int {
382 return $this->getDataSourceObject()->getNumberOfColumns();
386 * Get x data rows from the datasource.
388 * At this stage we are fetching from what has been stored in the form
389 * during `postProcess` on the DataSource form.
391 * In the future we will use the dataSource object, likely
392 * supporting offset as well.
398 * @throws \CRM_Core_Exception
399 * @throws \API_Exception
401 protected function getDataRows(int $limit): array {
402 return $this->getDataSourceObject()->getRows($limit);