fivejars/openy_traction_rec

为YMCA网站服务提供与Traction Rec CRM的集成

维护者

详细信息

github.com/fivejars/openy_traction_rec

源代码

问题

安装: 14

依赖: 0

建议者: 0

安全: 0

星标: 1

关注者: 4

分支: 4

开放问题: 1

类型:drupal-module

1.0.0-alpha.2 2022-02-03 20:26 UTC

Requires

LGPL-3.0-or-later 92e593b85276dc4018ec9eb551e4602f1bbbca98

This package is auto-updated.

Last update: 2024-09-25 09:27:56 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 Website Services Traction Rec: Activity Finder扩展了YMCA网站服务活动查找器的新字段和逻辑。
  • YMCA Website Services Traction Rec: PEF import提供PEF迁移。配置完成后，请参阅modules/openy_traction_rec_import/README.md了解导入内容的详细信息。
  • YMCA Website Services Traction Rec: SSO提供使用SSO登录用户并根据Traction Rec登录状态操作菜单项的可能性。请参阅modules/openy_traction_rec_sso/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）扩展
        • 为命名用户发布基于JSON Web Token (JWT)的访问令牌
      • 取消勾选OAuth部分中的所有其他选项。
    • 保存连接应用程序
  3. 保存应用程序后，您将需要获取 消费者详情
    • 在保存后出现的“我的连接应用程序”屏幕上单击 管理消费者详情（或通过 设置 > 应用程序管理器）。
    • 保存下一步骤所需的 消费者密钥 和 消费者密钥。
  4. 创建一个 配置文件 或 权限集 以分配权限给您的应用程序。我们建议使用 权限集，因为这些是 Salesforce 推荐的选项。
    1. 您的 Traction Rec 支持团队应该能够从他们的 dev1 实例部署 Traction Rec 活动查找权限集。如果已部署此权限集，请直接进入 用户 创建步骤。要从头创建 权限集
    • 设置 > 用户 > 权限集 > 新建
    • 填写您希望的 标签，并将 许可证 留为 --None--
    • 在新的 权限集 中，打开 对象设置。
    • 在非常长的 对象设置 列表中，对以下列出的每个 10 个 对象执行以下操作
      • 找到对象并点击打开它。在对象的配置屏幕中
        • 在 对象权限 下，将 读取 标记为 启用。
        • 在 字段权限 下，在标题字段上标记 读取访问 以提供对所有字段的访问权限。
      • 保存 对象设置 并搜索下一个。
    • 最后，审查访问权限摘要，确保为每个必要的对象提供了 读取 访问权限。
    1. 创建一个 配置文件
      • 您必须 在 创建用户之前 这样做。
      • 设置 > 用户 > 配置文件 > 新建
      • 当被问及要克隆哪个 现有配置文件 时，选择 标准用户 或 标准平台用户。务必注意与目标配置文件相关联的 用户许可证。
      • 在 非常大的 配置屏幕中，点击 编辑，然后
        • 在 连接应用程序访问 下，添加对您上面创建的连接应用程序的访问权限。
        • 搜索并启用以下 系统权限。
        • 在 自定义对象权限 下，添加对以下 对象 的 读取 访问权限。
      • 保存这些更改。
  5. 使用新的配置文件或权限集创建新的 用户
  • 设置 > 用户 > 新建用户
    • 用户许可证 - 您在上一步骤中创建配置文件时选择的选项，或 Salesforce。
    • 电子邮件 - 您将使用的有效电子邮件，用于接收登录验证。
    • 用户名 - 这 不是 您的电子邮件，并且必须在所有 Salesforce 组织中是唯一的。 这是以下 Drupal 连接中使用的名称。如果您输入了现有的用户名，您将收到以下错误

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

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

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

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

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

Salesforce 权限

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

  • 课程选项
  • 课程
  • 课程会话选项
  • 课程会话
  • 位置
  • 产品及折扣
  • 项目类别
  • 项目类别标签
  • 项目
  • 会话

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

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

在 Drupal 中配置连接

  1. 转到 管理 > 配置 > 系统 > 密钥 (/admin/config/system/keys) 创建一个新的密钥来存储上面创建的私钥。
    • 添加密钥
    • 添加 密钥名称 和 描述
    • 选择 密钥类型： "TractionRec JWT 私钥"
    • 根据您的配置选择 密钥提供程序。有关详细信息，请参阅 管理密钥。
    • 配置所选提供程序后，然后 保存 密钥。
  2. 转到 管理 > YMCA 网站服务 > 集成 > 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":"会话过期或无效","errorCode":"INVALID_SESSION_ID"])。
    • 根据公开可访问的注册链接设置 社区 URL。
      • 这可能类似于 https://my-ymca.my.site.com
      • URL 可在 Salesforce 中找到，在 设置 > 数字体验 > 所有站点。
    • 选择配置如上的密钥。

映射

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

对象映射

检索器输出以下文件

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

注意：拖动力“项目”及其子分组标签与Traction Rec不同

  • 拖动力：“项目类别”是“项目”的父级。
  • Drupal：“项目”是“项目子类别”的父级。

映射到Drupal字段

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

  • Drupal内容类型（捆绑）
    • Salesforce/TractionRec源字段 → Drupal目标字段
  • 项目 - 从programs.json / TREC项目类别
    • Id → id
    • Name → Title
    • Available → Published（《状态》）
  • 项目子类别 - 从program_categories.json/ TREC项目
    • Id → id
    • Name → Title
    • Program → Program（《field_category_program》）通过查找项目导入
    • Available → Published（《状态》）
  • 活动 - 从classes.json / TREC课程
    • Id → id
    • Name → Title
    • Program/Id → Program Subcategory（《field_activity_category》）通过查找项目子类别导入
    • Available → Published（《状态》）
  • 班级 - 从classes.json / TREC课程
    • Id → id
      • 班级ID也将用于设置活动（《field_class_activity》）
    • Name → Title
    • Program/Id → 忽略
    • Description/Rich Description → Description（《field_class_description》）
      • 如果设置了富描述，则使用它；否则使用描述字段。
    • Available → Published（《状态》）
  • 会话 - 从sessions.json / TREC会话
    • Course_Option/Name → Title
    • Course_Option/ID → id
      • 也用于生成注册链接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》）
      • 如果设置了富描述，则使用它；否则使用描述字段。
    • 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（《状态》）
    • Course_Option/Register_Online_From_Date → 未使用
    • Course_Option/Register_Online_To_Date → 未使用
    • Course_Option/Capacity → Initial Availability（《field_availability》）
    • 课程选项/可用总容量 → 初始可用性（field_availability）
    • 课程选项/无限容量 → 如果设置，则覆盖容量并设置初始可用性（field_availability）为100
    • 课程选项/无限等待名单容量 → 等待名单无限容量（waitlist_unlimited_capacity）
    • 课程选项/等待名单总容量 → 等待名单容量（waitlist_capacity）
    • 课程选项/产品/价格描述 → 价格描述（field_price_description）
    • 课程会话/ID → 通过查找课程导入设置课程（field_session_class）

数据模型

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

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

字段类型来自Salesforce的设置 > 对象管理器 > {实体} > 字段与关系。

  • 数字字段选项为：number(小数位数)