Add background_import param to import_records()

Setting this to True will ask REDCap to import records in the
background; this will work similarly to the background import in the
Data Import Tool.

Because this flag is not supported in old REDCap versions, if you do
not specify it, it will not be added to your request parameters at all
and you will get the default REDCap behavior.

Currently, REDCap defaults to foreground imports.

Author: njvack

redcap/methods/records.py

@@ -259,6 +259,7 @@ def import_records(
         record_type: Literal["flat", "eav"] = "flat",
         date_format: Literal["YMD", "DMY", "MDY"] = "YMD",
         force_auto_number: bool = False,
+        background_process: Optional[bool] = None,
     ):
         """
         Import data into the REDCap Project
@@ -298,6 +299,8 @@ def import_records(
                 of imported records by REDCap. If this is set to true, and auto-numbering
                 for records is enabled for the project, auto-numbering of imported records
                 will be enabled.
+            background_process:
+                Specifies whether to do the import as background process.
 
         Raises:
             RedcapError: Bad request made, double check field names and other inputs
@@ -321,6 +324,9 @@ def import_records(
         payload["type"] = record_type
         payload["dateFormat"] = date_format
         payload["forceAutoNumber"] = force_auto_number
+        if background_process is not None:
+            # This option is not supported in old REDCap versions (< 14.something)
+            payload["backgroundProcess"] = int(background_process)
 
         return_type = self._lookup_return_type(
             format_type=return_format_type,

tests/unit/test_simple_project.py

@@ -615,6 +615,68 @@ def test_df_import(simple_project):
     assert not "error" in response
 
 
+def test_import_records_background_process_true(simple_project, mocker):
+    """Test that background_process=True passes backgroundProcess=1 in payload"""
+    mocked_api_call = mocker.patch.object(
+        simple_project, "_call_api", return_value={"count": 1}
+    )
+
+    data = [{"record_id": "1", "test": "value"}]
+    simple_project.import_records(data, background_process=True)
+
+    args, _ = mocked_api_call.call_args
+    payload = args[0]
+
+    assert "backgroundProcess" in payload
+    assert payload["backgroundProcess"] == 1
+
+
+def test_import_records_background_process_false(simple_project, mocker):
+    """Test that background_process=False passes backgroundProcess=0 in payload"""
+    mocked_api_call = mocker.patch.object(
+        simple_project, "_call_api", return_value={"count": 1}
+    )
+
+    data = [{"record_id": "1", "test": "value"}]
+    simple_project.import_records(data, background_process=False)
+
+    args, _ = mocked_api_call.call_args
+    payload = args[0]
+
+    assert "backgroundProcess" in payload
+    assert payload["backgroundProcess"] == 0
+
+
+def test_import_records_background_process_none(simple_project, mocker):
+    """Test that background_process=None does not add backgroundProcess to payload"""
+    mocked_api_call = mocker.patch.object(
+        simple_project, "_call_api", return_value={"count": 1}
+    )
+
+    data = [{"record_id": "1", "test": "value"}]
+    simple_project.import_records(data, background_process=None)
+
+    args, _ = mocked_api_call.call_args
+    payload = args[0]
+
+    assert "backgroundProcess" not in payload
+
+
+def test_import_records_background_process_default(simple_project, mocker):
+    """Test that not specifying background_process does not add it to payload"""
+    mocked_api_call = mocker.patch.object(
+        simple_project, "_call_api", return_value={"count": 1}
+    )
+
+    data = [{"record_id": "1", "test": "value"}]
+    simple_project.import_records(data)
+
+    args, _ = mocked_api_call.call_args
+    payload = args[0]
+
+    assert "backgroundProcess" not in payload
+
+
 def test_reports_json_export(simple_project):
     report = simple_project.export_report(report_id="1")