服务器管理 > 使用事件触发器自动完成任务和计算数据 > 配置 Webhook 触发器以同步 PTC RV&S 中的 Codebeamer 变更包
配置 Webhook 触发器以同步 PTC RV&S 中的 Codebeamer 变更包
PTC RV&S 中的 Webhook 触发器
您可以在 PTC RV&S 中配置 Webhook 触发器,以支持以下用途:
1. 针对以下事件,通知 Codebeamer 有关变更包中的变更:
提交变更包
拒绝变更包
关闭变更包
执行变更包
重新开启变更包
放弃变更包条目
新建变型项目
删除变型项目
停用变型项目
激活变型项目
项目检查点
2. 用于验证尝试使用 Codebeamer 项创建变更包事件的用户和跟踪器项。
要在 PTC RV&S 中配置 Webhook 触发器,请执行以下步骤:
步骤 1:为 webhook 触发器配置源数据库
要使用 Webhook 触发器,请在 PTC RV&S 管理客户端的“配置管理” > “配置 > “特性”中配置以下特性:
特性
说明
mksis.si.webhook.enable
如果设置为 true,则启用 Webhook 事件触发器。
如果设置为 false,则忽略所有 Webhook 配置。
该特性的默认值为 true
mksis.si.webhook.notifier.maxThreads
设置可用于并发发送 webhook 通知的最大线程数。
增加此值可以提高发送大量 webhook 通知时的性能,但也可能会增加服务器的资源使用量。
该特性的默认值为 5。
mksis.si.webhook.notifier.retry.attemptDelay
用于设置延迟时间,经过该时间后将在重试队列中检查发送失败但准备好重试和重新提交的 Webhook 通知
较长的延迟可以避免因重试次数过多而导致 webhook 端点过载,但也可能会增加成功发送通知所需的时间。
该特性的默认值为 30 秒。
mksis.si.webhook.notifier.retry.cleanupDelay
设置从重试队列中移除失败 webhook 通知的延迟时间。
这有助于防止重试队列无限增长和消耗过多资源。
该特性的默认值为 300 秒。
mksis.si.webhook.notifier.retry.maxThreads
设置可用于重新并发发送失败 webhook 通知的最大线程数。
增加此值可以提高重试发送大量失败 webhook 通知时的性能,但也可能会增加服务器的资源使用量。
该特性的默认值为 2。
mksis.si.webhook.notifier.timeout
设置 webhook 通知发送尝试的超时时间。
如果 webhook 通知无法在此时间内发送,系统将视其为失败,并按照重试策略重试。
该特性的默认值为 2 秒。
mksis.si.webhook.trigger.script
在触发 webhook 事件时从 mksis.triggers.scripts 目录中执行的脚本。此脚本用于将 webhook 有效载荷发送到指定的 webhook URL。
请确保 mksis.triggers.scripts 目录中存在此脚本。如果未设置脚本,系统将不会发送 webhook 事件。
步骤 2:配置 webhook-config.properties 文件
更新 webhook-config.properties 文件 (位于 <Serverinstalldir>/data/triggers 目录)。
例如
# Webhook URL Configuration
webhooks.list=wb_project1,wb_project2
wb_project1.url=https://<codebeamer server>/<webhook URI for SCM Repository>
wb_project1.secret=<secret>
wb_project1.projectPath=/test1/project1.pj
wb_project2.url=https:////<codebeamer server>/<webhook URI for SCM Repository>
wb_project2.secret=<secret>
wb_project2.projectPath=/test1/project2.pj
要在创建变更包过程中验证用户和项,请更新 webhook-config.properties 文件,如下所示:
#Configure the Codebeamer API endpoint that would be invoked to get json response containing tracker item details 
webhook.itemvalidation.url=<protocol>://<hostname>:<port>/api/v3/items
#configure the timeout for item validation endpoint in ms. Default is 25 seconds.
webhook.itemvalidation.timeout=0
#configure the auth scheme for item validation.
webhook.itemvalidation.authscheme=oauth
#Configure OAuth details for a user, such as a service principal, that has access to the Codebeamer API and to Codebeamer projects that have RV&S SCM repositories created.
webhook.itemvalidation.oauth.clientid=
#Ensure to use an appropriate encryption technique to Encrypt clientsecret
webhook.itemvalidation.oauth.clientsecret=
webhook.itemvalidation.oauth.scope=
webhook.itemvalidation.oauth.tokenurl=
* 
Codebeamer 中创建的 PTC RV&S 外部 SCM 存储库中,可以获取 urlsecretprojectpath。有关详情,请参阅 Codebeamer 3.3 及更高版本帮助中心的在 Codebeamer 中创建 Webhook 密钥主题。
PTC 建议使用 OAuth 令牌身份验证进行用户验证。
确保以加密格式获取 clientsecret,并且必须在 webhook.js 内将其解密,以生成身份验证令牌。例如,如果 Base64 用作加密方式,则必须更新 webhook.js 以应用合适的 Base64 解码方法,从而衍生令牌。
步骤 3:配置 webhookevents.list 文件
<Serverinstalldir>/data/triggers 目录中,添加 webhookevents.list 文件。
在向 Codebeamer 发送 Webhook 通知时,以下是唯一支持的事件:
Server.submitChangePackage.post
Server.rejectChangePackage.post
Server.closeChangePackage.post
Server.commitChangePackage.post
Server.discardChangePackageEntry.post
Server.reopenChangePackage.post
Project.newVariant.post
Project.deleteVariant.post
Project.deactivateVariant.post
Project.activateVariant.post
Project.checkpoint.post
* 
可在 webhookevents.list 文件中配置 Server.createChangePackage.pre 事件,用于在创建变更包期间验证用户和项。它不会向 Codebeamer 发送任何 Webhook 通知。有关详情,请参阅下一部分。
步骤 4:配置 webhook.js 文件以进行用户和项验证
<Serverinstalldir>/data/triggers/scripts/webhook 目录中的 webhook.js 文件包含基于 webhook 配置进行 webhook 调用的代码。
以下两种方法必须根据用户和项的验证要求进行相应自定义配置。
例如:
function print(s){
webhookBean.logDebugMessage(s);
}
// Aborts script execution
{
environment.abortScript(msg,true);
}
#The function validateJsonResponse processes the JSON response from Codebeamer API endpoint and use it for validations.
#The below example demonstrates retrieving “assignedTo” field from response and comparing it with change package creator user from webhookBean”
#Update the function to add additional rules such as checking the “State” or other fields based on business requirements
function validateJsonResponse(jsonResponseObj) {
var JSONObject = Packages.org.json.JSONObject;
var body = jsonResponseObj;
// Parse JSON
var root = new JSONObject(body);
print("Payload root keys: " + root.keySet());
var assignedTo;
if (root.has("assignedTo")) {
assignedTo = root.getJSONArray("assignedTo");
} else {
abortScript("No user(s) assigned.");
}
if(!assignedTo || assignedTo == null){
abortScript("No user(s) assigned.");
}
var currentUser = webhookBean.getUserName();
var isAssigned = false;
for (var i = 0; i < assignedTo.length(); i++) {
var name = assignedTo.getJSONObject(i).getString("name");
if (name.equalsIgnoreCase(currentUser)) {
isAssigned = true;
break;
}
}
if(!isAssigned){
abortScript("Change Package creator and assigned user not matched.");
} else {
print("Assigned user validated successfully");
}
}
// OAuth token generation
function getOAuthAccessToken() {
try {
// Get OAuth configuration from webhook-config.properties
//Define a property and provide the client id for token generation.
var oauthClientId = webhookBean.getOauthClientId();
//Define a property and provide the client secret for token generation.
var oauthClientSecret = webhookBean.getOauthClientSecret();
//Define a property and provide the scope for token generation.
var oauthScope = webhookBean.getOauthScope();
//Define a property and provide the token URL for token generation.
var oauthTokenUrl = webhookBean.getOauthClientTokenUrl();
if (oauthClientId == null || oauthClientSecret == null || oauthScope == null || oauthTokenUrl == null) {
abortScript("OAuth configuration not found. Please set OAuthClientId, OAuthClientSecret, OAuthScope, and OAuthTokenUrl in webhook-config.properties");
}
//Ensure to use an appropriate decryption technique to retrieve oauthClientSecret received from getOauthClientSecret()
oauthClientSecret = new java.lang.String(java.util.Base64.getDecoder().decode(oauthClientSecret));
//Generate OAuth access token
var oauthAccessToken = environment.getAccessToken(oauthClientId, oauthClientSecret, oauthScope, oauthTokenUrl);
if (oauthAccessToken == null || oauthAccessToken.length() == 0) {
abortScript("Failed to generate OAuth access token");
}
print("getOAuthAccessToken : Token generated Successfully");
return "Bearer " + oauthAccessToken;
} catch (e) {
abortScript("Error generating OAuth token");
}
}
* 
这是一个示例脚本,展示了如何验证已分配用户。您可以根据业务需要修改脚本。
这对您有帮助吗?