ycloudyusa/openy_traction_rec

提供与 Traction Rec CRM 的集成，用于 YMCA 网站服务

维护者

详细信息

github.com/YCloudYUSA/openy_traction_rec

源代码

安装: 490

依赖: 0

建议者: 0

安全: 0

星标: 0

关注者: 0

分支: 4

类型:drupal-module

1.0.3 2024-06-28 18:42 UTC

Requires

LGPL-3.0-or-later 48d38ed53ea824ea087dc654b1ecca946a792c8b

This package is auto-updated.

Last update: 2024-09-16 16:49:59 UTC

README

本模块提供 YMCA 网站服务与 Traction Rec CRM 的集成。

安装

需要此模块

composer require ycloudyusa/openy_traction_rec

然后启用必要的模块和子模块

drush en openy_traction_rec openy_traction_rec_import openy_tr_activity_finder

使用

主模块本身仅提供 API，帮助从 TractionRec 获取数据。更具体的功能由子模块提供

  • YMCA 网站服务 Traction Rec: PEF 导入 提供PEF迁移。
  • YMCA 网站服务 Traction Rec: 活动查找器 扩展了 YMCA 网站服务活动查找器的新字段和逻辑。

配置完成后，请参阅 modules/openy_traction_rec_import/README.md 了解如何导入内容。

配置

在 Salesforce 中创建一个连接的应用

  1. 创建一个新的私有密钥和 X509 证书，根据您的组织调整命令中的 subj 选项。（参见 openssl-req 的手册 了解此处选项的含义。）
    openssl req -x509 -noenc -sha256 -days 365 \
 -keyout traction_rec.key \
 -out traction_rec.crt \
 -subj "/C=US/ST=Illinois/L=Chicago/O=My YMCA/OU=Org/emailAddress=youremail@example.com"
    • 证书中的电子邮件地址不需要与连接应用的电子邮件地址匹配。
    • 证书 必须每年更新一次（或达到设置的 --days 天数后）。我们建议您设置提醒，以防止不希望出现的故障。
  2. 在 Salesforce > 设置 > 应用管理器 中，创建一个新的 连接应用。
    • 设置 名称 和 电子邮件。
      • “联系电子邮件”不用于身份验证。
    • 勾选 启用 OAuth 设置
      • 将回调 URL 设置为您的网站的基本 URL
      • 勾选 使用数字签名 并上传上面创建的 X509 证书（.crt）。
      • 确保应用具有以下 已选 OAuth 范围
        • 完全访问（full）
        • 通过 API 管理用户数据（api）
        • 通过 Web 浏览器管理用户数据（web）
        • 在任何时间执行请求（refresh_token, offline_access）
      • 勾选这些选项
        • 对于支持的授权流程，要求代码交换证明密钥（PKCE）扩展
        • 为命名用户颁发基于 JWT 的访问令牌
      • 取消勾选 OAuth 部分中的所有其他选项。
    • 保存 连接应用
  3. 保存应用后，您需要获取 消费者详情
    • 在保存后出现的“我的连接应用”屏幕上（或通过 设置 > 应用管理器），点击 管理消费者详情。
    • 保存用于下一步的 消费者密钥 和 消费者密钥。
  4. 创建一个 配置文件 或 权限集 以将权限分配给您的应用。我们建议使用 权限集，因为这是 Salesforce 推荐的选项。
    1. 您的 Traction Rec 支持团队应该能够从他们的 dev1 实例中部署 Traction Rec Activity Finder Permission Set。如果已部署此权限集，请直接进入 用户 创建步骤。要从头创建 权限集
    • 设置 > 用户 > 权限集 > 新建
    • 根据您的意愿填写标签，并将许可证保留为--无--
    • 在新的权限集中，打开对象设置。
    • 在非常长的对象设置列表中，针对以下列出的10个对象执行以下操作
      • 找到对象并点击打开它。在每个对象的配置屏幕中
        • 在对象权限下，将读取标记为启用。
        • 在字段权限下，在表头字段上标记读取访问以提供对所有字段的访问。
      • 保存对象设置并搜索下一个。
    • 最后，查看访问权限摘要，确保为每个必要的对象提供了读取访问。
    1. 创建一个配置文件
      • 您必须在创建用户之前执行此操作。
      • 设置 > 用户 > 配置文件 > 新建
      • 当询问从哪个现有的配置文件克隆时，选择标准用户或标准平台用户。务必注意与目标配置文件相关联的用户许可证。
      • 在非常大的配置屏幕中，单击编辑，然后
        • 在连接应用访问下，添加您上面创建的连接应用的访问权限。
        • 搜索并启用以下系统权限。
        • 在自定义对象权限下，添加以下对象的读取访问权限。
      • 保存这些更改。
  5. 使用新的配置文件或权限集创建新的用户
  • 设置 > 用户 > 新建用户
    • 用户许可证 - 在上一步中创建配置文件时所选择的选项，或Salesforce。
    • 电子邮件 - 您将使用它来接收登录验证的工作电子邮件。
    • 用户名 - 这不是您的电子邮件，并且必须在整个 所有 Salesforce 组织 中是唯一的。 这是将在下面的 Drupal 连接中使用到的名称。 如果您输入了现有的用户名，您将收到以下错误

      错误：用户名重复。该用户名已存在于本组织或其他 Salesforce 组织中。用户名必须在所有 Salesforce 组织中是唯一的。要解决此问题，请使用不同的用户名（它不需要与用户的电子邮件地址匹配）。

    • 将用户分配给您上面创建的配置文件或具有必要权限的权限集。
      • 在权限集分配下，单击编辑分配
      • 找到您在上一步中创建的权限集，选择它，单击添加，然后单击保存。
  1. 确认您的连接应用、配置文件和用户已连接
    • 转到 设置 > 应用 > 连接应用 > 管理连接应用，选择您的新应用。如果它尚未显示在相关部分下，请分配包含您的新的用户的配置文件或权限集。
      • 单击 管理配置文件 或 管理权限集
      • 搜索您的配置文件或权限集并保存。
    • 在连接应用详情中，单击 编辑策略
      • 在 OAuth 策略 > 允许用户 下选择 管理员批准的用户预先授权。
      • 检查 发行基于 JSON Web Token (JWT) 的访问令牌。
      • 保存连接应用详情。

当过程完成时，您应该在以下关系之间有以下关系：用户、权限集 或 配置文件 和 连接应用

  • API 用户 应分配 权限集 或 配置文件。
  • 连接的应用 应分配相同的 权限集 或 配置文件。

仔细审查所有这些步骤。遗漏任何步骤都可能导致无法查询API。

销售力权限

销售力集成 权限集 或 配置文件 应具有以下对象中所有字段的读取访问权限

  • 课程选项
  • 课程
  • 课程会话选项
  • 课程会话
  • 地点
  • 产品和折扣
  • 项目类别
  • 项目类别标签
  • 项目
  • 会话

如果使用 配置文件，它还应具有以下系统权限

  • Apex REST服务
  • 查看限制和作用域规则
  • 使用REST API更新同意首选项

在Drupal中配置连接

  1. 转到 管理 > 配置 > 系统 > 密钥 (/admin/config/system/keys) 并创建一个新密钥来存储上面创建的私钥。
    • 添加密钥
    • 添加 密钥名称 和 描述
    • 选择 密钥类型： "TractionRec JWT私钥"
    • 根据您的配置选择 密钥提供者。有关详细信息，请参阅密钥管理。
    • 配置所选提供者然后 保存 密钥。
  2. 转到 管理 > YMCA网站服务 > 集成 > Traction Rec > Traction Rec身份验证设置 (/admin/openy/integrations/traction-rec/auth) 以配置Traction Rec提供的密钥和秘密。
    • 从Salesforce中的“管理消费者详情”添加 消费者密钥 和 消费者秘密。
    • 添加连接到连接应用的 用户。
      • 这是 用户名，而不是 联系邮箱。
    • 输入 登录URL。
      • 这很可能是 https://login.salesforce.com
    • 根据其描述设置 服务基本URL 和 REST API基本URL。
      • 确保REST API基本URL对curl -I响应为200。将类似*.lightning.force.com的URL替换为*.my.salesforce.com，因为lightning URL可能会导致重定向，从而导致身份验证错误，如([@"message":"Session expired or invalid","errorCode":"INVALID_SESSION_ID"])。
    • 根据公开可访问的注册链接设置 社区URL。
      • 这可能类似于 https://my-ymca.my.site.com
      • URL可以在Salesforce中的“设置 > 数字体验 > 所有站点”下找到。
    • 选择上面配置的密钥。

映射

TractionRec导入器从许多Traction Rec对象中提取数据（请参阅TractionRec.php以获取完整查询）

对象映射

提取器输出以下文件

  • classes.json - 来自课程
    • 映射到活动和课程。由于TREC没有这种区分，Drupal中生成的活动和课程中的信息是重复的。
  • locations.json - 来自地点
    • 此文件未使用，但地点通过会话导入映射到位置。
  • program_categories.json - 来自项目类别标签
    • 映射到项目。
  • programs.json - 来自项目
    • 映射到子类别。
  • sessions.json - 来自课程选项
    • 映射到会话。

注意： Traction Rec的“项目”及其子分组标签不同

  • Traction Rec：“项目类别”是“项目”的父类别。
  • Drupal: "Program" 是 "Program Subcategory" 的父级。

映射到 Drupal 字段

这些文件随后通过 导入器（以 migrate_plus. 开头的配置项）导入到 Drupal 内容中。导入过程如下：

  • Drupal 内容类型（包）
    • Salesforce/TractionRec 源字段 → Drupal 目标字段
  • Program - 从 programs.json / TREC 程序类别
    • Id → id
    • Name → Title
    • Available → Published (status)
  • Program Subcategory - 从 program_categories.json / TREC 程序
    • Id → id
    • Name → Title
    • Program → Program (field_category_program) 通过对 Program 导入的查找
    • Available → Published (status)
  • Activity - 从 classes.json / TREC 课程
    • Id → id
    • Name → Title
    • Program/Id → Program Subcategory (field_activity_category) 通过对 Program Subcategory 导入的查找
    • Available → Published (status)
  • Class - 从 classes.json / TREC 课程
    • Id → id
      • 课程 Id 也将用于设置活动 (field_class_activity)
    • Name → Title
    • Program/Id → 忽略
    • Description/Rich Description → Description (field_class_description)
      • 如果设置了 Rich Description，则使用它，否则使用 Description 字段。
    • Available → Published (status)
  • Session - 从 sessions.json / TREC 会话
    • Course_Option/Name → Title
    • Course_Option/ID → id
      • 还用于生成注册链接 URL，该 URL 使用在 Traction Rec 身份验证设置中设置的社区 URL（/admin/openy/integrations/traction-rec/auth）。
    • Course_Session/Course/Id → Class
    • Course_Session/Course/Name → Course
    • Course_Session/Course/Description & Rich_Description → Description (field_class_description)
      • 如果设置了 Rich Description，则使用它，否则使用 Description 字段。
    • Course_Option/Start_Date → Session Time > Start date
    • Course_Option/Start_Time → Session Time > Start time
    • Course_Option/End_Date → Session Time > End date
    • Course_Option/End_Time → Session Time > End time
    • Course_Option/Day_of_Week → Session Time > Days
    • Course_Option/Age_Min → Min Age (field_session_min_age) 转换为月份
    • Course_Option/Age_Max → Max Age (field_session_max_age) 转换为月份
    • Course_Option/Location/Name → Location (field_session_location)
      • 位置名称用作备用，以防位置映射不匹配。
    • Course_Option/Location/Id → Location (field_session_location)
      • 位置 ID 用于在 Traction Rec 导入器设置中的位置映射中尝试匹配位置（/admin/openy/integrations/traction-rec/importer）
    • Course_Option/Instructor → Instructor (field_session_instructor) 截至到 255 个字符
    • Course_Option/Available_Online → Online registration (field_session_online)
    • Course_Option/Available → Published (status)
    • Course_Option/Register_Online_From_Date → 未使用
    • Course_Option/Register_Online_To_Date → 未使用
    • Course_Option/Capacity → Initial Availability (field_availability)
    • Course_Option/Total_Capacity_Available → Initial Availability (field_availability)
    • Course_Option/Unlimited_Capacity → 如果设置，则覆盖容量并将 Initial Availability (field_availability) 设置为 100
    • Course_Option/Unlimited_Waitlist_Capacity → Wait list Unlimited Capacity (waitlist_unlimited_capacity)
    • Course_Option/Waitlist_Total → Wait list capacity (waitlist_capacity)
    • Course_Option/Product/Price_Description → Price description (field_price_description)
    • Course_Session/Id → Class (field_session_class) 通过对 Class 导入的查找

数据模型

此模块假设其查询中的 Traction Rec "标准" 数据模型。任何与此模型不符的偏差都需要在 src/TractionRec.php 中覆盖查询。

此模型包含 Traction Rec 中与我们的使用相关的字段的子集。所有实体都比列出的字段更多。

字段类型来自 Salesforce 的 Setup > Object Manager > {Entity} > Fields & Relationships。

  • 数字字段选项为： number(length_decimal places)