IAddViaTemplateCmd::Initialize

The Initialize method is used to configure the AddViaTemplate operation, including providing the client with the ability to customize the dialog title. This method also enables the client to specify information about the item to be added, such as the name and directory location of the file on the local machine, the XML for the item properties, and the relationship to establish between the item being added and other items that have already been added to the object store. The entry template information is obtained through the use of the SelectEntryTemplate command.

Records Management

When Records Manager is enabled for the Application Engine, the Initialize method can be used to specify whether the Declare Record operation should be made available for the specified object store. If the object store has the Records Manager feature enabled, and the bDeclareRecordOn parameter is set to VARIANT_TRUE, then the DeclareRecord button will be visible on the Confirmation page of the Add Via Template Wizard. The user can then click DeclareRecord to execute the Declare Record operation.

The Declare Record operation will be executed on every document represented by an ID in the vDocumentIDs parameter, including the newly added document. If the vDocumentIDs parameter is empty, the operation will only be performed on the new document. If the bDeclareRecordOn parameter is set to VARIANT_FALSE, the vDocumentIDs parameter will be ignored and the DeclareRecord button will not be visible.

NOTE When Records Manager is not enabled for the Application Engine or the object store does not have the Records Manager feature enabled, both the bDeclareRecordOn and vDocumentIDs parameters will be ignored. However, if Workplace determines that the Declare Record operation must be made available, then the DeclareRecord button will be visible, even if the Entry Template specifies that the Confirmation page should be hidden.

void spIAddViaTemplateCmd->Initialize(_bstr_t bstrDialogTitle,
                                      _bstr_t bstrPathName,
                                      IObjectStoreItemPtr spIObjectStoreItemEntryTemplate,
                                      _bstr_t bstrPropertiesXml,
                                      VARIANT vLinkDescriptors,
                                      VARIANT_BOOL bDeclareRecordOn,
                                      VARIANT vDocumentIDs);
Parameters
bstrDialogTitle - [in] Required _bstr_t, which specifies the label to display in the title bar of the Add Via Template Wizard dialog when the AddViaTemplate command is invoked. By using this parameter, client applications can customize the title that appears at the top of the Wizard dialog to correspond with their application requirements.
bstrPathName - [in] Required _bstr_t, which specifies the fully qualified name and directory location of the file on the local machine that is to be added.
spIObjectStoreItemEntryTemplate - [in] Required pointer to an IObjectStoreItem interface, which specifies a GUID of a specific version series ID for the object store item for which to apply to the added item. The entry template is returned by the ISelectEntryTemplateRsp interface.
bstrPropertiesXml - [in] Required _bstr_t, the XML which specifies the properties to apply to the item during the AddViaTemplate operation, where the XML must be of the form:
<properties>
   <property>
      <symname>SymbolicName</symname>
      <values>
         <value>PropertyValue</value>
         <value>...</value></values>
   </property>
   <property>
      ...
   </property>
</properties>
vLinkDescriptors - [in] Required pointer to a VARIANT, which contains a SAFEARRAY of LinkDescriptor components that specify the links to be established between the item being added and other (already existing) items in the object store. Each ILinkDescriptor represents a linked object to be created. When no links are required, a value of VT_EMPTY should be specified.
bDeclareRecordOn - [in] Required VARIANT_BOOL, which represents whether the DeclareRecord button should be visible on the Confirmation page of the Add Via Template Wizard. This parameter can be set to the following:
- VARIANT_TRUE, the DeclareRecord button will be visible.
- VARIANT_FALSE, the DeclareRecord button will not be visible.
vDocumentIDs - [in] Required pointer to a VARIANT, which contains a SAFEARRAY of the IDs (GUIDs) for the documents which already exist in the specified object store. If the object store does not yet contain any documents, a value of VT_EMPTY should be specified. NOTE This parameter is ignored when the bDeclareRecordOn parameter is set to VARIANT_FALSE.
Results
This method always returns an HRESULT value of S_OK if successful.
Sample
The following is a fragment from the complete example for the AddViaTemplate command.
   ...
   // Instantiate the custom SelectEntryTemplate command component
   // to obtain the desired entry template from the user
   ISelectEntryTemplateCmdPtr spISelectEntryTemplateCmd;
hResult = spISelectEntryTemplateCmd.CreateInstance(__uuidof(SelectEntryTemplateCmd));
if (FAILED(hResult)) {
std::cout << "Could not create the SelectEntryTemplate command component.\n"; _ASSERTE(0);
} // Initialize the custom SelectEntryTemplate command component with the // page title, object store name, and template type(s). _bstr_t bstrPageTitle = (_T("Customized Select Entry Template Operation")); _bstr_t bstrObjectStoreName = (_T("Alaska")); AppIntTemplateType enTemplateTypes = TemplateTypes_Document; std::cout << "Initializing the SelectEntryTemplate command component..." << std::endl; spISelectEntryTemplateCmd->Initialize(bstrPageTitle, bstrObjectStoreName, enTemplateTypes); // Execute the SelectEntryTemplate command and capture the response component std::cout << "Executing the SelectEntryTemplate command..." << std::endl; IAppIntCmdPtr spIAppIntCmd(spISelectEntryTemplateCmd);
IAppIntRspPtr spIAppIntRsp = spIAppIntCmd->Invoke(spIAppIntSession); // Determine if the command failed, before accessing response component data hResult = spIAppIntRsp->GetHResult(); if (FAILED(hResult)) { std::cout << "The SelectEntryTemplate command failed to execute." << std::endl; // Examine the error information provided in the standard response component _bstr_t bstrErrorName = spIAppIntRsp->GetErrorName(); std::cout << "ErrorName=" << ( bstrErrorName.length() ? (LPCSTR) bstrErrorName : _T( "" ) ) << std::endl; _bstr_t bstrErrorMsg = spIAppIntRsp->GetErrorMsg(); std::cout << "ErrorMsg=" << ( bstrErrorMsg.length() ? (LPCSTR) bstrErrorMsg : _T( "" ) ) << std::endl; _bstr_t bstrErrorDetails = spIAppIntRsp->GetErrorDetails(); std::cout << "ErrorDetails=" << ( bstrErrorDetails.length() ? (LPCSTR) bstrErrorDetails : _T( "" ) ) << std::endl; _ASSERTE(0); } else { std::cout << "The SelectEntryTemplate command succeeded." << std::endl; // Obtain the entry template contained in the custom SelectEntryTemplateRsp component ISelectEntryTemplateRspPtr spISelectEntryTemplateRsp(spIAppIntRsp);
_ASSERTE(spISelectEntryTemplateRsp != 0);
IObjectStoreItemPtr spIObjectStoreItemEntryTemplate = spISelectEntryTemplateRsp->GetObjectStoreItem();
_ASSERTE(spIObjectStoreItem != 0); std::cout << "Details for the entry template selected by the user:<< std::endl;
std::cout << "ObjectStoreName=" << (LPCSTR) spIObjectStoreItemEntryTemplate->GetObjectStoreName() << std::endl;
std::cout << "ItemType=" << (LPCSTR) CItemTypeConverter::EnumToBSTR(spIObjectStoreItemEntryTemplate->GetItemType()) << std::endl;
std::cout << "VersionSeriesID=" << (LPCSTR) spIObjectStoreItemEntryTemplate->GetVersionSeriesID() << std::endl;
std::cout << "VersionID=" << (LPCSTR) spIObjectStoreItemEntryTemplate->GetVersionID() << std::endl; } // Instantiate the custom AddViaTemplate command component IAddViaTemplateCmdPtr spIAddViaTemplateCmd;
hResult = spIAddViaTemplateCmd.CreateInstance(__uuidof(AddViaTemplateCmd));
if (FAILED(hResult)) {
std::cout << "Could not create the AddViaTemplate command component.\n"; _ASSERTE(0);
} // Create the LinkDescriptors for the item to Add const DWORD cNumElements = 2; long lCount = 0; COleSafeArray saLinks(VT_DISPATCH, cNumElements); { // Instantiate a LinkDescriptor component
ILinkDescriptorPtr spILinkDescriptor0(__uuidof(LinkDescriptor)); _ASSERTE(spILinkDescriptor != 0); // Instantiate the ObjectStoreItem component IObjectStoreItemPtr spIObjectStoreItem0; hResult = spIObjectStoreItem0.CreateInstance(__uuidof(ObjectStoreItem));
if (FAILED(hResult)) {
std::cout << "Could not create the ObjectStoreItem component.\n"; _ASSERTE(0);
} // Initialize the ObjectStoreItem component with // the items' type, name, version series ID and version ID. ItemType eItemType = eItemTypeDocument; _bstr_t bstrObjectStoreName = (_T("Alaska")); _bstr_t bstrVersionSeriesID = (_T("{6BC064A2-2D58-4B0A-AEF2-B2F8A1100000}")); _bstr_t bstrVersionID = (_T("{DDE54469-36D9-4fe9-8676-445E4994DE1F}")); std::cout << "Initializing the ObjectStoreItem component..." << std::endl;
spIObjectStoreItem0->Initialize(eItemType, bstrObjectStoreName, bstrVersionSeriesID, bstrVersionID); _bstr_t bstrLinkClassID = (_T("{C91111A9-CE9C-43e6-8548-8A08F43F9726}")); RelationshipType enLinkType = eTypeLinkTo; // Define the XML properties for the item to Link std::cout << "Defining the XML item properties..." << std::endl; _bstr_t bstrLinkPropertiesXml = _T( "" ); bstrLinkPropertiesXml += _T("<properties>");
bstrLinkPropertiesXml += _T("<property>");
bstrLinkPropertiesXml += _T("<symname>DocumentTitle</symname>"); bstrLinkPropertiesXml += _T("<values>");
bstrLinkPropertiesXml += _T("<value>LinkedDocument.doc</value></values>");
bstrLinkPropertiesXml += _T("</property>");
bstrLinkPropertiesXml += _T("<property>");
bstrLinkPropertiesXml += _T("<symname>CommentReq</symname>"); bstrLinkPropertiesXml += _T("<values>");
bstrLinkPropertiesXml += _T("<value>This will be a linked document.</value></values>");
bstrLinkPropertiesXml += _T("</property>");
bstrLinkPropertiesXml += _T("<property>");
bstrLinkPropertiesXml += _T("<symname>SVCPStr</symname>"); bstrLinkPropertiesXml += _T("<values>");
bstrLinkPropertiesXml += _T("<value>This is the SVCPStr property</value></values>");
bstrLinkPropertiesXml += _T("</property>");
bstrLinkPropertiesXml += _T("</properties>"); // Initialize the LinkDescriptor component to hold the link std::cout << "Initializing LinkDescriptor component 1..." << std::endl; spILinkDescriptor0->Initialize(spIObjectStoreItem0, bstrLinkClassID, enLinkType, bstrLinkPropertiesXml); if(spILinkDescriptor0) { saLinks.PutElement(&lCount, spILinkDescriptor0); } } { lCount++; // Instantiate a LinkDescriptor component
ILinkDescriptorPtr spILinkDescriptor1(__uuidof(LinkDescriptor)); _ASSERTE(spILinkDescriptor != 0); // Instantiate the ObjectStoreItem component IObjectStoreItemPtr spIObjectStoreItem1; hResult = spIObjectStoreItem1.CreateInstance(__uuidof(ObjectStoreItem));
if (FAILED(hResult)) {
std::cout << "Could not create the ObjectStoreItem component.\n"; _ASSERTE(0);
} // Initialize the ObjectStoreItem component with // the items' type, name, version series ID and version ID. ItemType eItemType = eItemTypeDocument; _bstr_t bstrObjectStoreName = (_T("Alaska")); _bstr_t bstrVersionSeriesID = (_T("{2400406D-68FE-4d5c-81FD-AC01F7186119}")); _bstr_t bstrVersionID = (_T("{6D770D89-497C-40be-B300-E646FC12DE8A}")); std::cout << "Initializing the ObjectStoreItem component..." << std::endl;
spIObjectStoreItem1->Initialize(eItemType, bstrObjectStoreName, bstrVersionSeriesID, bstrVersionID); _bstr_t bstrLinkClassID = (_T("{C91111A9-CE9C-43e6-8548-8A08F43F9726}")); RelationshipType enLinkType = eTypeLinkTo; // No XML properties for this Link item _bstr_t bstrLinkPropertiesXml = VT_EMPTY; // Initialize the LinkDescriptor component to hold the link std::cout << "Initializing LinkDescriptor component 2..." << std::endl; spILinkDescriptor1->Initialize(spIObjectStoreItem1, bstrLinkClassID, enLinkType, bstrLinkPropertiesXml); if(spILinkDescriptor1) { saLinks.PutElement(&lCount, spILinkDescriptor1); } } _variant_t vLinkDescriptors(saLinks); // Define the XML properties for the item to Add std::cout << "Defining the XML item properties..." << std::endl; _bstr_t bstrPropertiesXml = _T( "" ); bstrPropertiesXml += _T("<properties>");
bstrPropertiesXml += _T("<property>");
bstrPropertiesXml += _T("<symname>DocumentTitle</symname>"); bstrPropertiesXml += _T("<values>");
bstrPropertiesXml += _T("<value>AddedDocument.doc</value></values>");
bstrPropertiesXml += _T("</property>");
bstrPropertiesXml += _T("<property>");
bstrPropertiesXml += _T("<symname>CommentReq</symname>"); bstrPropertiesXml += _T("<values>");
bstrPropertiesXml += _T("<value>This document contains new information to be added.</value></values>");
bstrPropertiesXml += _T("</property>");
bstrPropertiesXml += _T("<property>");
bstrPropertiesXml += _T("<symname>SVCPStr</symname>"); bstrPropertiesXml += _T("<values>");
bstrPropertiesXml += _T("<value>This is the SVCPStr property</value></values>");
bstrPropertiesXml += _T("</property>");
bstrPropertiesXml += _T("</properties>"); // Initialize the custom AddViaTemplate command component with the dialog title, // name and directory location of the file on the local machine, // the entry template selected by the user, // as well as the XML properties and LinkDescriptors. _bstr_t bstrDialogTitle = (_T("Customized AddViaTemplate Operation")); _bstr_t bstrPathName = (_T("C:\Temp\DocumentToBeAdded.doc")); VARIANT_BOOL bDeclareRecordOn = VARIANT_FALSE; _variant_t vDocumentIDs(); std::cout << "Initializing the AddViaTemplate command component..." << std::endl; spIAddViaTemplateCmd->Initialize(bstrDialogTitle, bstrPathName, spIObjectStoreItemEntryTemplate, bstrPropertiesXml, vLinkDescriptors, bDeclareRecordOn, vDocumentIDs); ...