在IBM Business Process Manager V8.5中定制文档列表控件

我的团队从事的IBM BPM项目之一需要以下功能：

• 向人员服务添加和检索附件。 它应该只检索相关文档，而不是所有文档，例如默认控件。
• 在人工服务中为教练添加了不止一种类型的附件，例如需要在一个选项卡中添加一种类型的文档，而在另一选项卡中的同一教练中添加不同类型的文档。
• 删除必须以编程方式控制的文档。
• 替换随附的文档。
• 将附加文档的文档ID和名称存储在记录系统（SOR）数据库中。

基于这些要求，我的团队决定自定义“文档列表”控件。 为了实现前两个功能，我们使用了以下BPMDocumentOptions属性： displayOptions和uploadOptions 。 该控件不提供删除附件的功能，也不提供替换附件文档的功能，因此我们需要添加这些功能。

本教程中显示的增强功能不会替换文档，它会隐藏版本图标以模拟替换，因此人工服务用户只能看到最新的文档。 ECMDocumentInfo的默认变量不提供检索文档Id和Name ，因此您需要创建一个新变量以绑定到此控件以检索文档ID和名称以及URL。

您需要使用以下配置变量和服务来增强控制：

• 将布尔变量添加到控件以显示/隐藏“删除”按钮。
• 添加一个布尔变量以显示/隐藏“修订”按钮。 如果隐藏“修订”按钮，则只能查看上载文档的最新版本。
• 当用户单击“删除”按钮时，添加服务以删除附件。

创建一个Ajax服务以删除附件

您需要一项服务才能从IBM BPM文档存储中删除附件。 IBM BPM提供了一个删除文档的API。 当用户单击列表控件中的“删除”图标时，将调用该服务。 完成以下步骤以创建服务：

1. 使用名为uniqueDocKey的键和默认的uniqueDocId创建一个环境变量。
2. 创建一个Ajax服务并将其命名为Delete ECM Document 。 声明以下三个变量，如图1所示。

   图1. Delete ECM Document服务的三个输入参数

   
3. 从托盘拖放Content Integration图标，然后对其进行配置，如图2所示。
4. 在“ 实施”选项卡上，选择“企业内容管理”服务器下的“ 使用数据映射 ”。 在内容操作下，选择“ 删除文档”操作（图2）。

   图2.配置内容集成控件

   
5. 在“ 数据映射”选项卡上，设置第一步中声明的三个变量，如图3所示。

   图3. Delete ECM Document服务的数据映射

   

为文档列表控件创建绑定变量对象

用于绑定到“文档列表”控件的默认ECMDocumentInfo对象将绝对URL返回给ECMDocumentInfo 。 但是，我们的要求是获取为文档输入的名称以及要存储在SOR数据库中的唯一文档ID。 为此，我们声明了一个具有以下属性的名为RSADocumentInfo的新业务对象：

• docName ：提供给附件的名称。
• docId ：唯一的文档ID。
• versionId ：如果需要versionSeriesId 。
• filename ：附件文件名。
• contentURL ：IBM BPM文档存储中文档的绝对URL。

自定义文档列表控件的脚本和资源包

现在，您需要更新资源包以提供标签的属性，两个变量的帮助提示以及所添加的一项服务。 在教练中使用它们时，它们将显示在控件的“配置”选项卡中。

1. 复制文档列表控件，然后将该副本重命名为您的要求。 本教程中的示例使用RSA Document List 。
2. 要自定义资源束，请复制资源束DocumentList并将其重命名为RoyaltyDocumentList 。
3. 在业务数据下的变量选项卡中，将documentInfos的变量类型从ECMDocumentInfo为RSADocumentInfo 。
4. 对于Delete变量，创建两个变量，如图4所示。

   图4. canBeDeleted属性的资源包

   
5. 第一个标签canBeDeleted提供了“配置”选项卡中变量标签的文本。 当鼠标悬停在“配置”选项卡中的“ 可以删除”标签上时，第二个变量用于帮助提示。 本教程中的示例显示了英语语言环境的帮助提示。 但是，您可以为该工具支持的所有语言添加它们。 图5显示了英语语言环境的附加值，但是如果您熟悉另一种语言，则可以添加标签。

   图5.仅用于英语存储的资源包值

   

   同样，再创建两个对（请参见图6和图7）。

   图6. deleteDocument服务的资源包变量

   

   图7. specialDocuments资源包变量（隐藏版本图标）

   
6. 打开“ RSA文档列表”向导视图（控件），然后转到“ 变量”选项卡。 在Configuration Options下 ，添加以下变量，如图8所示。

   图8.三个新属性– 2个变量，1个服务

   
7. 单击canBeDeleted，然后选择“类型”作为“ 对象”和“变量类型”作为“ 布尔” 。 在资源包的右侧选择Label and Documentation ，如图9所示。

   图9. canBeDeleted属性的配置

   
8. 对specialDocuments重复该步骤（如图10所示）。 True表示在控件中隐藏“修订”按钮。

   图10. specialDocuments属性的配置

   
9. 对DeleteDocument重复此步骤，它是一项服务，而不是变量。 对于Type ，选择Service （如图11所示）。 在“默认服务”上，选择您先前创建的“ 删除ECM文档”服务。

   图11. DeleteDocument服务的配置（配置为Type）

   

自定义DocumentList.js脚本

将您的自定义文件的内容从“文档列表”控件复制到外部编辑器中，并将其另存为RoyaltyDocumentList.js 。 更改代码，如以下示例所示。 粗体显示的代码是添加的自定义项，因此您可以搜索上面的行以了解将其添加到何处。

1. 如果删除操作失败，请注意错误文本消息：

   var documentListView_documentSearchError = "Error retrieving documents.";
   
   // Extension Begin
   var documentListView_documentDeleteDocumentError = "Error deleting the current document.";
   // Extension End
   
   var documentListView_documentSearchError_missingProperties = "An error
   occurred while processing the search result. A search query must include
   the following properties: ${0}.";

2. 请注意鼠标悬停在“删除”按钮上时显示的消息：

   var documentListView_versionsTitle = "Revisions";
   // Extension Begin
   var documentListView_deleteTitle = "Delete";
   // Extension End
   
   var documentListView_URLHeader = "File Name or URL";

3. 找到函数DocumentListControl 。 构造URL来调用Delete函数，还声明两个变量以读取“配置”选项卡中设置的值：

   this.getTypesUrl = convertURLtoCurrentSnapshotId(context.options.getTypeDescendants.url,
    this.portalContextRoot);
   
   // Extension Begin
   this.deleteDocUrl = convertURLtoCurrentSnapshotId(context.options.deleteDocument.url,
   this.portalContextRoot);
   // Extension End
   
   
   this.allowCreate = false;
   this.allowUpdate = false;
   this.openInNewWindow = false;
   this.showAllContent = false;
   
   // Extension Begin
   this.canBeDeleted = false;
   this.specialDocumenets = false;
   // Extension End
   
   this.documentsXML; // Set of documents to be displayed in the view

4. 找到reInitializeConfigOptions函数并添加以下代码以读取在控件的“配置”选项卡中设置的值：

   DocumentListControl.prototype.reInitializeConfigOptions = function() {
   	this.maxItems = (this.context.options.numberOfResultsToShow &&
    this.context.options.numberOfResultsToShow.get("value") > 0) ?
   this.context.options.numberOfResultsToShow.get("value") : 10;
   
   // Extension Begin
   this.canBeDeleted = this.context.options.canBeDeleted ?
   this.context.options.canBeDeleted.get("value") : false;
   this.specialDocumenets = this.context.options.specialDocumenets ?
   
   // Extension Begin
   
   	//this will determine the type of ecm server being used
   //(BPM Documents ECM Documents)
   	this.useBPMDocuments = this.context.options.useBPMDocuments ?
   this.context.options.useBPMDocuments.get("value") : "ECM";
   
   	}

5. 添加以下代码以调用Delete ECM Document服务以删除附件：

   /**
   * Delete document whose document id is passed. (TBD)
   */
   
   DocumentListControl.prototype.deleteDocument = function(documentId) {
   
   	inputParameters='<input name=\"elementValue\">';
   	inputParameters+='<variable name=\"documentId\">' + documentId +
   '</variable>';
   	inputParameters+='<variable name=\"allVersions\">true</variable>';
   	inputParameters+='<variable name=\"serverName\">' +
   this.ecmServerConfigurationName + '</variable>';
   	inputParameters+='</input>';
   
   	var deleteDocUrl = this.deleteDocUrl + '&input=' + inputParameters;
   	dojo.xhrGet ({
   		url: deleteDocUrl,
   		handleAs: "xml",
   		load : dojo.hitch(this, function(xmlDoc) {
   			alert("Document Successfully Deleted !");		
   		 		 		 //this.refresh();	
   						 if(this.skipCount >= this.maxItems)
   							this.skipCount -=  this.maxItems;
   						 if(this.pageNumber > 1)
   							this.pageNumber--;			
   						this.loadDocumentList();	 
   		}),
          		 error: dojo.hitch(this, function(o) {
           		alert("Error Deleting The Document");
           	})
       });
   }

6. 查找以下功能。 您需要为网格中的“删除”按钮添加图像。 在此，选择负号图像进行删除。

   DocumentListControl.prototype.initImages = function() {
   	this.navRevisionImgHover.src = this.teamworksContextRoot
   +"/images/ECM/ecm_documentversions_hover_image.png"
   
   	// Extension Begin
   this.delImg = new Image();
   	this.delImg.src = this.teamworksContextRoot +"/images/minus.gif"
   	this.delImgHover = new Image();
   	this.delImgHover.src = this.teamworksContextRoot +"/images/minusc.gif"
   }
   // Extension End

7. 查找以下函数并对其进行自定义：

   DocumentListControl.prototype.displayContent = function() {

8. Java脚本具有用于文件名和版本系列ID的变量，但是没有用于文档名称的变量。 您需要声明文档名称，如以下示例所示：

   var idNameColumn=-1; // Column containing the document name
   	// Extension Begin
   	var docName = null;  // variable to get the document name
   	// Extension End

9. 使用以下代码捕获文档名称：

   // Extension Begin
   if(idNameColumn == totalColumns)
   	docName = dataItems[j].childNodes[0].data;
   // Extension End
   
   if(isBPMUrl == true || idNameColumn == totalColumns){
   dataContent = htmlStringDecoder(dataContent);
   }

10. 使用以下代码实例化控件的有界变量并填充值。 将ECMDocumentInfo对象替换为RSADocumentInfo 。 除少数几行代码外，大多数增强功能都是替代项。 仔细检查代码。

    //Set up the RSADocumentInfo link: either link to document or url
    //(url is used with IBM BPM Documents)
    
    // Extension Begin
    RSADocumentInfo = new Object();
    RSADocumentInfo.docName = docName;
    RSADocumentInfo.docId = documentId;
    RSADocumentInfo.versionId = versionSeriesId;
    ;
    
    if(bpmFileType != null && bpmFileType == BPMDoc_fileType_url) {
    	 =
    buildURLString(this.portalContextRoot)
    + bpmContentURL;
    	bpmContentURL = null;
    	bpmFileType = null;
    } else {
     = documentUrl;
    	documentUrl = null;
    }
    
    if (this.dataBinding) {
    if(this.dataBindingList != this.originalDataBindingList)
    		this.originalDataBindingList.add();
    
    	// Add RSADocumentInfo to the databinding list
    	this.dataBindingList.add();
    }
    
    …..
    
    if (this.openInNewWindow == true) {
    	previewIcon.onclick = dojo.hitch(this,
    this.openLinkInNewWindow,
    , true, tr);
    ...
    // Extension End

11. 使用以下代码隐藏或显示“修订历史记录”按钮，具体取决于在specialDocument属性中设置的值：

    if (this.canViewVersions && versionSeriesId != undefined &&!this.specialDocumenets) {
    	var versionsIcon = createAndAppendChildElement('a',
    tdActions, "");
    	this.createHoverLink(versionsIcon,
    this.navRevisionImg,
    this.navRevisionImgHover, "", false,
    documentListView_versionsTitle, 16, 16);

12. 根据canBeDeleted变量中设置的值，使用以下代码显示或隐藏“删除”按钮并调用onclick函数：

    if(this.canBeDeleted)  {
    		var deleteIcon = createAndAppendChildElement('a',
    tdActions, "");
    		this.createHoverLink(deleteIcon, this.delImg,
    this.delImgHover, "", false,
    documentListView_deleteTitle, 16, 16);
    
    		deleteIcon.onclick = dojo.hitch(this, function(docId) {
    		this.deleteDocument(docId)
    		}, documentId);
    		}
    
    		currentRow++;

创建一个使用“文档列表”控件的样本人工服务

现在，您需要测试增强的“文档列表”控件。 您创建了一个人工服务，并在其教练中使用“文档列表”控件。

1. 创建人员服务并声明以下三个属性，如图12所示。

   图12. Document List控件的变量

   
2. 创建图13所示的图。

   图13.人员服务设计

   
3. 将以下内容放入Initialize Document Key JavaScript控件中：

   //The following variable can be populated using any of the Human
   //Service variable, constant string so that it will be unique across
   //all your DocumentList control instances in all human services.
   
   tw.local.documentContextString =
   "CoverPage_CoverPageInstance1_CoverPageDocumentId"
   
   tw.local.docOps = new tw.object.BPMDocumentOptions();
   
   tw.local.docOps.displayOptions = new tw.object.BPMDocumentDisplayOptions();
   tw.local.docOps.displayOptions.displayProperties = new 
   tw.object.listOf.NameValuePair();
   tw.local.docOps.displayOptions.displayProperties[0] =
   new tw.object.NameValuePair()
   tw.local.docOps.displayOptions.displayProperties[0].name = tw.env.uniqueDocKey;
   tw.local.docOps.displayOptions.displayProperties[0].value =
   tw.local.documentContextString;
   tw.local.docOps.displayOptions.displayMatchRule = "ANY"
   
   tw.local.docOps.uploadOptions = new tw.object.BPMDocumentUploadOptions();
   tw.local.docOps.uploadOptions.addProperties = true;
   tw.local.docOps.uploadOptions.uploadProperties = new 
   tw.object.listOf.NameValuePair();
   tw.local.docOps.uploadOptions.uploadProperties[0] =
   new tw.object.NameValuePair();
   tw.local.docOps.uploadOptions.uploadProperties[0].name= tw.env.uniqueDocKey;
   tw.local.docOps.uploadOptions.uploadProperties[0].value =
   tw.local.documentContextString;
   
   //Tw.local.documentContextString provide any string that uniquely
   //identifies the documents that are being attached in the current
    //instance of the control.
   //Where tw.env.uniqueDocKey = "UniqueDocId". As this is a literal string
    //and has to be used for all instances of the documentList control as
    //the parameter name, I have declared this as environment variable so
   // we avoid misspelling it.

4. 在教练中，放下RSADocumentList教练视图。
5. 在“绑定”下，选择documentInfo变量，如图14所示。

   图14.文档列表控件，General选项卡

   
6. 在Configuration选项卡上，配置人员服务，如图15所示。

   图15.文档列表控件，“配置”选项卡

   
   • 对于IBM BPM文档选项，选择docOps变量。
   • 对于“可以删除”，选中复选框。
   • 对于特殊/其他文档，请选中该复选框。
   • 对于“删除文档服务”，选择在第一步“ 删除ECM文档”中创建的Ajax服务。
7. 现在运行人员服务并对其进行测试。 您还可以从本教程的“ 下载”部分下载示例人员服务的代码。 Fileupload_Service.zip文件包含一个用于IBM BPM V8.5.6的Fileupload_Service.twx文件和一个更新的Fileupload_Service_v856.twx文件。

结论

本教程描述了如何在IBM BPM V8.5中增强文档列表控件。 现在，您可以实施功能并根据自己的需求自定义它们。

致谢

BPM Practitioners成员给作者的电子邮件中建议了将自定义名称和值属性传递给控件的想法和示例代码。

---

翻译自: https://www.ibm.com/developerworks/bpm/bpmjournal/1409_channapatna/1409_channapatna.html