datai/datai-scenes/datai-scene-salesforce/docs/api-docs/task/ObjectInsertTask.md

ObjectInsertTask - 对象自动插入任务

任务信息

• 任务名称: ObjectInsertTask
• Bean 名称: objectInsertTask
• 类路径: com.datai.integration.task.ObjectInsertTask
• 执行方法: autoInsertObjects(String targetOrgType) 或 autoInsertObjects()
• 模块归属: Salesforce 集成 - 定时任务
• 创建日期: 2026-01-16
• 最后更新: 2026-01-16

功能描述

自动扫描所有对象，判断是否满足插入条件，并调用相应的插入方法，将本地数据库中的对象数据插入到目标系统（如 Sandbox 环境或生产环境）。

执行条件

插入条件

1. isCreateable = true（可创建）

   • 对象必须在 Salesforce 中可创建

2. totalRows > 0（对象有本地数据）

   • 对象在本地数据库中有数据需要插入

3. 对象配置完整

   • api 不为空
   • label 不为空

方法参数

autoInsertObjects(String targetOrgType)

参数名	类型	必填	描述	示例	默认值
targetOrgType	String	否	目标ORG类型	"Sandbox", "Production"	"Sandbox"

autoInsertObjects()

无参数，使用默认目标ORG类型 "Sandbox"。

执行流程

开始
  ↓
检查 targetOrgType 参数
  ↓
参数为空？
  ├─ 是 → 使用默认值 "Sandbox"
  │
  └─ 否 → 使用传入的参数值
  ↓
查询所有对象
  ↓
遍历每个对象
  ↓
判断是否满足插入条件
  ↓
满足条件？
  ├─ 是 → 调用 insertObjectDataToTarget(id, targetOrgType)
  │         ↓
  │       记录成功/失败
  │         ↓
  │       继续下一个对象
  │
  └─ 否 → 跳过，记录日志
            ↓
          继续下一个对象
  ↓
输出统计信息
  ↓
结束

执行结果统计

任务执行完成后，会输出以下统计信息：

统计项	描述
扫描对象数	共扫描的对象总数
成功插入数	成功插入的对象数量
跳过数	不满足插入条件被跳过的对象数量
失败数	插入失败的对象数量

日志输出

INFO 级别

开始执行对象自动插入任务，目标ORG类型: Sandbox
目标ORG类型为空，使用默认值: Sandbox
开始插入对象数据到目标系统，对象ID: 1, API: Account, 目标ORG类型: Sandbox
对象数据插入成功，对象ID: 1, API: Account
对象自动插入任务完成，共扫描 10 个对象，成功插入 8 个，跳过 2 个，失败 0 个

DEBUG 级别

对象不满足插入条件，跳过插入，对象ID: 2, API: Contact

ERROR 级别

插入对象数据失败，对象ID: 3, API: Opportunity
执行对象自动插入任务失败

异常处理

任务级别异常

• 捕获所有异常，记录错误日志
• 不影响其他对象的插入操作
• 任务继续执行直到所有对象处理完成

对象级别异常

• 捕获单个对象插入失败的异常
• 记录错误日志，包含对象ID和API
• 增加失败计数，继续处理下一个对象

配置示例

Quartz 任务配置

INSERT INTO sys_job (job_name, job_group, invoke_target, cron_expression, status, remark)
VALUES (
  '对象自动插入任务',
  'DEFAULT',
  'objectInsertTask.autoInsertObjects',
  '0 0 3 * * ?',
  '0',
  '每天凌晨3点执行对象自动插入任务（使用默认目标ORG类型：Sandbox）'
);

使用自定义目标ORG类型

如果需要插入到不同的目标ORG，可以修改 invoke_target 字段：

UPDATE sys_job
SET invoke_target = 'objectInsertTask.autoInsertObjects("Production")'
WHERE job_name = '对象自动插入任务';

Cron 表达式说明

字段	值	说明
秒	0	第0秒
分	0	第0分
时	3	凌晨3点
日	*	每天
月	*	每月
周	?	不指定

注意事项

1. 执行时间建议

   • 建议在对象同步任务之后执行（如凌晨3点）
   • 确保本地数据库已有最新数据

2. 目标ORG类型

   • 默认使用 "Sandbox" 环境
   • 插入到生产环境前，务必在 Sandbox 环境充分测试
   • 可以通过参数指定不同的目标ORG类型

3. 对象配置要求

   • 确保对象的 api 和 label 字段不为空
   • 确保对象可创建（isCreateable = true）
   • 确保对象有本地数据（totalRows > 0）

4. 性能考虑

   • 对象数量较多时，任务执行时间可能较长
   • 建议监控任务执行时间，必要时调整执行频率
   • 考虑分批插入以避免API限流

5. 数据一致性

   • 插入前确保本地数据与目标系统数据不冲突
   • 建议在插入前进行数据校验
   • 记录插入失败的记录，便于后续处理

相关接口

• insertObjectDataToTarget - 插入单个对象数据到目标系统
• insertMultipleObjectDataToTarget - 插入多个对象数据到目标系统

相关文档

• 需求文档 - 定时任务自动同步、插入和更新对象数据
• 架构决策 - 定时任务自动同步、插入和更新对象数据
• 变更记录 - 定时任务自动同步、插入和更新对象数据

测试信息

测试环境

• 环境: 开发环境
• 版本: v1.0

测试用例

测试场景	输入参数	预期结果	实际结果	状态
正常插入（默认ORG）	无参数	成功插入满足条件的对象到Sandbox	成功插入满足条件的对象到Sandbox	通过
正常插入（自定义ORG）	"Production"	成功插入满足条件的对象到Production	成功插入满足条件的对象到Production	通过
跳过不可创建的对象	isCreateable = false	跳过该对象	跳过该对象	通过
跳过无数据的对象	totalRows = 0	跳过该对象	跳过该对象	通过
插入失败	目标系统不可用	记录失败，继续下一个对象	记录失败，继续下一个对象	通过

实现细节

• 使用 @Component("objectInsertTask") 注解注册为 Spring Bean
• 使用 @Slf4j 注解进行日志记录
• 使用 @Autowired 注入 IDataiIntegrationObjectService
• 提供两个重载方法：无参方法使用默认目标ORG类型，有参方法使用指定的目标ORG类型
• 遍历所有对象，逐个判断插入条件
• 调用 objectService.insertObjectDataToTarget(id, targetOrgType) 执行插入
• 记录详细的日志信息，便于问题排查