IAddCmd::Initialize

The Initialize method is used to configure the Add 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.

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 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.

void spIAddCmd->Initialize(_bstr_t bstrDialogTitle,
                           _bstr_t bstrPathName,
                           _bstr_t bstrRootDocClass,
                           VARIANT_BOOL bRestrictClass,
                           _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 Wizard dialog when the Add 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 name and directory location of the file on the local machine that is to be added.
bstrRootDocClass - [in] Required _bstr_t, that specifies the root document class ID (GUID) to display and select for use by the Add operation, which can be set as follows:
- a GUID identifying the specific root document class.
- an empty string "" signifying that any class may be selected by the user.
bRestrictClass - [in] Required VARIANT_BOOL, which represents the class ID(s) that should be made available for selection and use by the Add operation. This parameter can be set to the following:
- VARIANT_TRUE, only allow the root document class ID specified in bstrRootDocClass to be selected.
- VARIANT_FALSE, allow the root document class ID specified in bstrRootDocClass or any of its' children to be selected.
NOTE When bstrRootDocClass is empty, only the base Document class may be selected, regardless of whether bRestrictClass has been set to true or false.
bstrPropertiesXml - [in] Required _bstr_t, the XML which specifies the properties to apply to the item during the Add 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 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 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 Add command.
   ...
   // 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 Add command component with the dialog title, // name and directory location of the file on the local machine, // a specific root document class ID, the class ID choice restriction, // as well as the XML properties and LinkDescriptors. _bstr_t bstrDialogTitle = (_T("Customized Add Operation")); _bstr_t bstrPathName = (_T("C:\Temp\DocumentToBeAdded.doc")); _bstr_t bstrRootDocClass = (_T("{379B665E-1BBA-4BEA-AA4A-BE678369F2CC}")); VARIANT_BOOL bRestrictClass = VARIANT_TRUE; VARIANT_BOOL bDeclareRecordOn = VARIANT_FALSE; _variant_t vDocumentIDs(); std::cout << "Initializing the Add command component..." << std::endl; spIAddCmd->Initialize(bstrDialogTitle, bstrPathName, bstrRootDocClass, bRestrictClass, bstrPropertiesXml, vLinkDescriptors, bDeclareRecordOn, vDocumentIDs); ...