流程操作

约 2119 字大约 7 分钟

2025-02-17

注意

以下示例中，engine实例获取方式，请参考 H3.IEngine

获取流程Id

氚云的流程操作API，很关键的一个参数是流程Id，所以开篇，先介绍一下获取流程Id的几种方式：

获取当前流程表单的流程Id

注意

因为只有在表单后端中才能对应上唯一的流程Id，所以以下示例代码仅用于表单后端代码中。

protected override void OnLoad(H3.SmartForm.LoadSmartFormResponse response)
{
    string insId = this.Request.InstanceId;

    base.OnLoad(response);
}

protected override void OnSubmit(string actionName, H3.SmartForm.SmartFormPostValue postValue, H3.SmartForm.SubmitSmartFormResponse response)
{
    string insId = this.Request.InstanceId;

    base.OnSubmit(actionName, postValue, response);
}

通过业务对象实例获取流程Id

每个业务对象实例对应一条数据，而一条数据只有一个流程，在业务对象中就有一个属性 WorkflowInstanceId，对应的是该数据的流程Id。

业务对象获取可以参考业务对象，这里只做一个简单示例：

H3.DataModel.BizObject bo = H3.DataModel.BizObject.Load(H3.Organization.User.SystemUserId, this.Engine, "表单编码", "数据Id", false);
if(bo != null)
{
    string insId = bo.WorkflowInstanceId;
}

通过SQL查流程Id

通过表单主表查出数据对应流程Id：

SELECT WorkflowInstanceId FROM i_D154601HolidayRecord WHERE ObjectId = '数据Id'

通过流程实例表查出数据对应流程Id：

SELECT ObjectId FROM H_WorkflowInstance WHERE SchemaCode = '表单编码' AND ObjectId = '数据Id'

重新激活流程

注意

此API只针对已生效/已作废流程使用，并且只调用本API，流程会激活，但是流程不处于任何一个节点上，所以一般需要配合激活某个活动节点一起使用。

H3.Workflow.Messages.ActivateInstanceMessage actInsMessage = new H3.Workflow.Messages.ActivateInstanceMessage("流程Id");
engine.WorkflowInstanceManager.SendMessage(actInsMessage);

结束流程

注意

此API只针对进行中流程使用。

H3.Workflow.Instance.WorkflowInstance instance = engine.WorkflowInstanceManager.GetWorkflowInstance("流程Id");
H3.Workflow.Messages.FinishInstanceMessage finishMessage = new H3.Workflow.Messages.FinishInstanceMessage("流程Id",(int)instance.FinalTokenId);
engine.WorkflowInstanceManager.SendMessage(finishMessage);

取消流程

注意

只可对进行中数据使用。

H3.Workflow.Messages.CancelInstanceMessage cancelMessage = new H3.Workflow.Messages.CancelInstanceMessage("流程Id", false);
engine.WorkflowInstanceManager.SendMessage(cancelMessage);

激活某个活动节点

注意

激活流程节点，只是将流程节点进行了激活，效果类似于管理员手动更换处理节点，无法达到审批人审批通过的效果。一般配合重新激活流程/取消某个活动节点一起使用。

string insId = "流程Id";
string activityCode = "流程节点编码";

// 节点审批人，氚云用户Id数组，分两种情况：
// 1、传入用户Id，如：new string[]{ "用户Id 1", "用户Id 2" }，则激活节点后由定义用户审批
///2、传入new string[]{ }，则由流程引擎自动按配置分配审批人
string[] approvalIds = new string[]{ };

//参数对应描述：流程实例ID，活动节点编码，令牌ID，参与者，前驱令牌，是否检测入口条件，激活类型
H3.Workflow.Messages.ActivateActivityMessage actMessage = new H3.Workflow.Messages.ActivateActivityMessage(insId,
    activityCode, H3.Workflow.Instance.Token.UnspecifiedId, approvalIds, null, false, H3.Workflow.WorkItem.ActionEventType.Adjust);

//1.不会取消正在运行的节点。2.进行中的流程才能激活调整。
engine.WorkflowInstanceManager.SendMessage(actMessage);

取消某个活动节点

注意

必须是已经处于活动中的节点，才能进行取消，在流程日志上，本API操作显示为已取消。

string insId = "流程Id";
string activityCode = "流程节点编码";

H3.Workflow.Messages.CancelActivityMessage cancelMessage = new H3.Workflow.Messages.CancelActivityMessage(insId, activityCode, false);
engine.WorkflowInstanceManager.SendMessage(cancelMessage);

创建表单数据并发起流程

H3.IEngine engine = this.Engine;
//获取表单实例
H3.DataModel.BizObjectSchema schema = engine.BizObjectManager.GetPublishedSchema("表单编码");
//获取当前登录人
string createdBy = this.Request.UserContext.UserId;

H3.DataModel.BizObject newBo = new H3.DataModel.BizObject(engine, schema, H3.Organization.User.SystemUserId);
//将业务对象创建者设置为 当前登录人
newBo.CreatedBy = createdBy;
//将业务对象归属人设置为 当前登录人，注：流程将由归属人发起
newBo.OwnerId = createdBy;

//设置业务对象控件值
newBo["IssueReportName"] = "关于****的整改报告";

//设置业务对象流程实例Id
newBo.WorkflowInstanceId = System.Guid.NewGuid().ToString();
//创建业务对象
H3.ErrorCode errCode = newBo.Create();
if(errCode != H3.ErrorCode.Success)
{
    throw new Exception(schema.DisplayName + "创建失败: " + errCode);
}

//启动流程
string workItemID = string.Empty;
string errorMsg = string.Empty;
//获取流程模板
H3.Workflow.Template.WorkflowTemplate wfTemp = engine.WorkflowTemplateManager.GetDefaultWorkflow(schema.SchemaCode);
//发起流程（注意：第1个参数是流程发起人，此参数必须传真实用户Id，不可以是H3.Organization.User.SystemUserId，否则系统会随机选取一名用户作为发起人）
engine.WorkflowInstanceManager.OriginateInstance(newBo.OwnerId, schema.SchemaCode, wfTemp.WorkflowVersion, newBo.ObjectId, newBo.WorkflowInstanceId, H3.Workflow.WorkItem.AccessMethod.Web, true, string.Empty, true, out workItemID, out errorMsg);
if(!string.IsNullOrEmpty(errorMsg))
{
    throw new Exception(schema.DisplayName + "流程实例创建失败：" + errorMsg);
}

OriginateInstance方法说明：

H3.Workflow.Messages.WorkflowInstanceChangeSet OriginateInstance(
    string userId, //流程发起人，此参数请传业务对象的归属人，传其他用户Id无效
    string schemaCode, //表单编码
    int workflowVersion, //流程版本，此示例中固定从流程模板中获取
    string bizObjectId, //业务对象数据ObjectId
    string instanceId, //流程实例Id
    H3.Workflow.WorkItem.AccessMethod accessPoint, //操作终端，固定值：H3.Workflow.WorkItem.AccessMethod.Web
    bool finishStartActivity, //是否发起时自动提交，true：提交，会自动跳过发起节点，到达下一审批节点；false：仅创建流程但不提交
    string destActivityCode, //目标审批节点编码，固定值：string.Empty
    bool returnWorkItem, //是否返回流程项，固定值：true
    out string workItemId, //返回的流程项Id
    out string errorMessage //创建流程实例失败的异常信息
)

已有草稿数据，发起流程

注意

请注意，此示例只能用于已创建好的草稿数据，不能用于流程进行中/生效/作废的数据。流程进行中/生效/作废的数据想要重新发起流程，应先把数据状态Update为草稿状态，再来发起流程。

H3.IEngine engine = this.Engine;
//获取表单实例
H3.DataModel.BizObjectSchema schema = engine.BizObjectManager.GetPublishedSchema("表单编码");
//获取业务对象
H3.DataModel.BizObject draftBo = ...(此处省略获取业务对象代码);

//设置业务对象流程实例Id
draftBo.WorkflowInstanceId = System.Guid.NewGuid().ToString();
//将流程实例Id更新到业务对象中
H3.ErrorCode errCode = draftBo.Update();
if(errCode != H3.ErrorCode.Success)
{
    throw new Exception(schema.DisplayName + "更新失败: " + errCode);
}

//启动流程
string workItemID = string.Empty;
string errorMsg = string.Empty;
//获取流程模板
H3.Workflow.Template.WorkflowTemplate wfTemp = engine.WorkflowTemplateManager.GetDefaultWorkflow(schema.SchemaCode);
//发起流程（注意：第1个参数是流程发起人，此参数必须传真实用户Id，不可以是H3.Organization.User.SystemUserId，否则系统会随机选取一名用户作为发起人）
engine.WorkflowInstanceManager.OriginateInstance(draftBo.OwnerId, schema.SchemaCode, wfTemp.WorkflowVersion, draftBo.ObjectId, draftBo.WorkflowInstanceId, H3.Workflow.WorkItem.AccessMethod.Web, true, string.Empty, true, out workItemID, out errorMsg);
if(!string.IsNullOrEmpty(errorMsg))
{
    throw new Exception(schema.DisplayName + "流程实例创建失败：" + errorMsg);
}

流程结束/重新激活事件

当流程状态发生改变时，会触发 OnWorkflowInstanceStateChanged 事件，该事件有两个传入参数：oldState、newState，所以就能用来判断当前为结束时触发，还是重新激活时触发。

注意事项：

事件会在业务规则执行后触发
当表单配置了流程，在导入生效数据时，由于导入时会创建流程并结束流程，所以也会触发 OnWorkflowInstanceStateChanged 事件
这里只是提醒开发者在用这个事件时要考虑导入触发的情况，但是并不推荐开发者利用这个事件去做导入执行代码的需求，具体原因请看：为何不推荐利用OnWorkflowInstanceStateChanged事件做导入触发代码的需求
本事件无需用户进行调用，将事件写在表单设计-后端代码的 OnSubmit 方法之下即可。当流程状态发生改变时，流程引擎会自动调用 OnWorkflowInstanceStateChanged

代码示例：

protected override void OnSubmit(string actionName, H3.SmartForm.SmartFormPostValue postValue, H3.SmartForm.SubmitSmartFormResponse response)
{
    base.OnSubmit(actionName, postValue, response);
}

// 放在表单设计-后端代码的 OnSubmit 事件之下，无需在其他地方调用
protected override void OnWorkflowInstanceStateChanged(H3.Workflow.Instance.WorkflowInstanceState oldState, H3.Workflow.Instance.WorkflowInstanceState newState)
{
    // 流程审批结束后
    if(oldState == H3.Workflow.Instance.WorkflowInstanceState.Running && newState == H3.Workflow.Instance.WorkflowInstanceState.Finished)
    {
        // 业务代码
        // 配置了流程，且导入生效数据，也会触发本事件

        // 获取 H3.Iengine 实例
        H3.IEngine engine = this.Engine;

        // 获取当前业务对象
        H3.DataModel.BizObject bo = this.Request.BizObject;

        // 因为OnWorkflowInstanceStateChanged事件没有OnSubmit事件的base.OnSubmit调用
        // 所以，如果在本事件里修改当前业务对象的控件值，需要在修改完后，要自行调用Update来生效修改
        bo["F00000001"] = "我在流程结束时变更了";
        H3.ErrorCode errCode = bo.Update();
        if(errCode != H3.ErrorCode.Success)
        {
            throw new Exception(bo.Schema.DisplayName + "更新失败: " + errCode);
        }
    }

    // 流程重新激活
    if(oldState == H3.Workflow.Instance.WorkflowInstanceState.Finished && newState == H3.Workflow.Instance.WorkflowInstanceState.Running)
    {
        // 业务代码

    }

    base.OnWorkflowInstanceStateChanged(oldState, newState);
}

获取当前流程运行节点

由于 this.Request.ActivityCode 方法，获取的只是当前登录人所在的流程节点，会导致审批流节点的错乱，故使用：this.Request.WorkflowInstance.RunningActivties，获取当前流程的活动节点。

补充条例：

this.Request.WorkflowInstance.RunningActivties，获取到的值是一个[]数组，取值需做循环或者是通过索引获取。

代码示例：

 protected override void OnSubmit(string actionName, H3.SmartForm.SmartFormPostValue postValue, H3.SmartForm.SubmitSmartFormResponse response)
{
    string[] workCode = this.Request.WorkflowInstance.RunningActivties;
    if(actionName == "Submit" && workCode[0] == "Activity1")
    {
        this.Request.BizObject["F0000001"] = "当前流程为:"+ workCode[0];
    }
}