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 'dateFormats' => 'DataSource',
108 'savedMapping' => 'DataSource',
109 'dataSource' => 'DataSource',
113 * Get the submitted value, accessing it from whatever form in the flow it is
116 * @param string $fieldName
119 * @throws \CRM_Core_Exception
121 public function getSubmittedValue(string $fieldName) {
122 if ($fieldName === 'dataSource') {
123 // Hard-coded handling for DataSource as it affects the contents of
124 // getSubmittableFields and can cause a loop.
125 return $this->controller
->exportValue('DataSource', 'dataSource');
127 $mappedValues = $this->getSubmittableFields();
128 if (array_key_exists($fieldName, $mappedValues)) {
129 return $this->controller
->exportValue($mappedValues[$fieldName], $fieldName);
131 return parent
::getSubmittedValue($fieldName);
136 * Get values submitted on any form in the multi-page import flow.
140 public function getSubmittedValues(): array {
142 foreach (array_keys($this->getSubmittableFields()) as $key) {
143 $values[$key] = $this->getSubmittedValue($key);
149 * Get the available datasource.
151 * Permission dependent, this will look like
153 * 'CRM_Import_DataSource_CSV' => 'Comma-Separated Values (CSV)',
154 * 'CRM_Import_DataSource_SQL' => 'SQL Query',
157 * The label is translated.
161 protected function getDataSources(): array {
163 foreach (['CRM_Import_DataSource_SQL', 'CRM_Import_DataSource_CSV'] as $dataSourceClass) {
164 $object = new $dataSourceClass();
165 if ($object->checkPermission()) {
166 $dataSources[$dataSourceClass] = $object->getInfo()['title'];
173 * Get the name of the datasource class.
175 * This function prioritises retrieving from GET and POST over 'submitted'.
176 * The reason for this is the submitted array will hold the previous submissions
177 * data until after buildForm is called.
179 * This is problematic in the forward->back flow & option changing flow. As in....
181 * 1) Load DataSource form - initial default datasource is set to CSV and the
182 * form is via ajax (this calls DataSourceConfig to get the data).
183 * 2) User changes the source to SQL - the ajax updates the html but the
184 * form was built with the expectation that the csv-specific fields would be
186 * 3) When the user submits Quickform calls preProcess and buildForm and THEN
187 * retrieves the submitted values based on what has been added in buildForm.
188 * Only the submitted values for fields added in buildForm are available - but
189 * these have to be added BEFORE the submitted values are determined. Hence
190 * we look in the POST or GET to get the updated value.
192 * Note that an imminent refactor will involve storing the values in the
193 * civicrm_user_job table - this will hopefully help with a known (not new)
194 * issue whereby the previously submitted values (eg. skipColumnHeader has
195 * been checked or sql has been filled in) are not loaded via the ajax request.
197 * @return string|null
199 * @throws \CRM_Core_Exception
201 protected function getDataSourceClassName(): string {
202 $className = CRM_Utils_Request
::retrieveValue(
207 $className = $this->getSubmittedValue('dataSource');
210 $className = $this->getDefaultDataSource();
212 if ($this->getDataSources()[$className]) {
215 throw new CRM_Core_Exception('Invalid data source');
219 * Allow the datasource class to add fields.
221 * This is called as a snippet in DataSourceConfig and
222 * also from DataSource::buildForm to add the fields such
223 * that quick form picks them up.
225 * @throws \CRM_Core_Exception
227 protected function buildDataSourceFields(): void
{
228 $dataSourceClass = $this->getDataSourceObject();
229 if ($dataSourceClass) {
230 $dataSourceClass->buildQuickForm($this);
235 * Get the relevant datasource object.
237 * @return \CRM_Import_DataSource|null
239 * @throws \CRM_Core_Exception
241 protected function getDataSourceObject(): ?CRM_Import_DataSource
{
242 $className = $this->getDataSourceClassName();
244 /* @var CRM_Import_DataSource $dataSource */
245 return new $className($this->getUserJobID());
251 * Allow the datasource class to add fields.
253 * This is called as a snippet in DataSourceConfig and
254 * also from DataSource::buildForm to add the fields such
255 * that quick form picks them up.
257 * @throws \CRM_Core_Exception
259 protected function getDataSourceFields(): array {
260 $className = $this->getDataSourceClassName();
262 /* @var CRM_Import_DataSource $dataSourceClass */
263 $dataSourceClass = new $className();
264 return $dataSourceClass->getSubmittableFields();
270 * Get the default datasource.
274 protected function getDefaultDataSource(): string {
275 return 'CRM_Import_DataSource_CSV';
279 * Get the fields that can be submitted in the Import form flow.
281 * These could be on any form in the flow & are accessed the same way from
285 * @throws \CRM_Core_Exception
287 protected function getSubmittableFields(): array {
288 $dataSourceFields = array_fill_keys($this->getDataSourceFields(), 'DataSource');
289 return array_merge($this->submittableFields
, $dataSourceFields);
293 * Create a user job to track the import.
297 * @throws \API_Exception
299 protected function createUserJob(): int {
300 $id = UserJob
::create(FALSE)
302 'created_id' => CRM_Core_Session
::getLoggedInContactID(),
303 'type_id:name' => 'contact_import',
304 'status_id:name' => 'draft',
305 // This suggests the data could be cleaned up after this.
306 'expires_date' => '+ 1 week',
308 'submitted_values' => $this->getSubmittedValues(),
313 $this->setUserJobID($id);
321 * @throws \API_Exception
322 * @throws \Civi\API\Exception\UnauthorizedException
324 protected function updateUserJobMetadata(string $key, array $data): void
{
325 $metaData = array_merge(
326 $this->getUserJob()['metadata'],
329 UserJob
::update(FALSE)
330 ->addWhere('id', '=', $this->getUserJobID())
331 ->setValues(['metadata' => $metaData])
333 $this->userJob
['metadata'] = $metaData;