Batch Object
The Batch object is passed as an argument to all event handlers. The same object is available for each event in a batch operation.
-
A single-document operation is treated as a batch with size 1.
-
The Batch object is not supported by the CAD application links in remote mode.
Batch Object Properties
The Batch object provides the following properties, most of which are read-only. To affect some read-only properties requires user interaction or custom event procedures.
Argument Property
A variable stored for the Batch object during the current batch operation. Arguments can be used to pass parameters between procedures within the same batch operation.
Syntax
Argument(Name) As Variant
Following are the predefined, read-only Batch object arguments that you can use to obtain additional information that may be useful when working with particular events.
| Argument | Description |
|---|---|
|
Batch.Argument("__$$RelatedProjectCopy") |
A reference to the project copy document that is being released as a master document. Useful in the DocGenericEvent_BeforeNewDocument event to move the master document to the correct location if it is being created for the first time. |
|
Batch.Argument("__$$RelatedVaultDocument") |
A reference to a vault document that corresponds to briefcase file. The reference can be a ID string, Document object, or AMDocument object. Useful in the BrcEvent_BeforeImport event to relate a vault document to an incoming file. |
|
Batch.Argument("DocumentPath") |
Provides the location of the document in the local workspace starting from the root of the vault. This event will only process if the NewLibraryComponentDocType setting is disabled. |
|
Batch.Argument("MatchedTypes") |
Provides a semicolon-delimited list of internal type names matched to the document extension. This event will only process if the NewLibraryComponentDocType setting is disabled. |
Remarks
The value of Name is case-sensitive.
For more information about arguments, see Object Arguments.
ApplyToAll Property
Indicates whether a user selected the Apply for all other documents of this type option that is shown on wizard pages for batches of documents during custom command execution. The default is True.
Syntax
ApplyToAll As Boolean
Remarks
This property can be set in the <CommandName>_Initialize event using the constant AS_CONFIRM_APPLY_FOR_ALL to specify whether the default behavior should be to apply a stored value to all documents in the batch. The property can then be tested in the <CommandName>_BeforeWizard and <CommandName>_AfterWizard events to determine if the wizard was shown, the user changed the option, and if the properties on the wizard page have been applied to the first document in the batch and will be applied to the next document in the batch.
In PowerWeb, the same result is achieved by setting Batch.ApplyToAll to True in the relevant Initialize event the same result is achieved in PowerWeb. For example:
Sub DocCopyMoveEvent_InitializeCopy(Batch, TargetFolder)
Batch.ApplyToAll = True 'Apply to all option in wizard default on
End SubThis works in all cases except Single Document Workflow (DocWorkflowEvent_InitializeChangeWFState) and Configurable Workflow (DocCWFEvent_InitializeExecuteTransition).
BatchIndex Property
Index of the current item in a batch operation. Starts at 1. Read-only.
Syntax
BatchIndex As Long
BatchSize Property
Number of items in the current batch operation. Returns 1 for non-batch operations. Read-only.
Syntax
BatchSize As Long
ConfirmationTitle Property
CountFailed Property
The number of operations in the current batch that failed. Read-only.
Syntax
CountFailed As Long
CountSucceeded Property
The number of operations in the current batch that succeeded. Read-only.
Syntax
CountSucceeded As Long
IsFirstInBatch Property
True only for the first item in a batch operation. True for single documents. Read-only.
Syntax
IsFirstInBatch As Boolean
IsLastInBatch Property
True only for the last item in a batch operation. True for single documents. Read-only.
Syntax
IsLastInBatch As Boolean
ProcessAsBatch Property
Set to True to indicate that the current (custom) command acts as a batch operation upon the members of the Batch object. Set to False (default) to act only upon the selected document.
Set this property to True in the DocGenericEvent_PrepareCommand event before programmatically adding documents with the Batch.AddDocuments method in a custom command's Initialize event.
Syntax
ProcessAsBatch As Boolean
Batch Object Methods
The Batch object methods affect the current batch operation. They are described below.
Abort Method
Abort the current batch operation.
Syntax
Abort([Message])
| Name | Description |
|---|---|
|
Message |
Show the specified message to the current user. |
Remarks
Uncommitted items in the batch are revoked.
AddDocuments Method
Adds the members of the specified collection to the Batch object.
Syntax
AddDocuments(Collection As Object)
| Name | Description |
|---|---|
| Collection |
A collection of documents to add to the Batch object. Can be the result of Vault.FindDocuments or Document.GetReferences |
Remarks
Not available in PowerWeb. This method is intended to be used in a custom command's Initialize event to add documents to a batch for processing.
AddDocumentToBatch Method
Adds a specified document to the Batch object.
Syntax
AddDocumentToBatch(DocID As String)
| Name | Description |
|---|---|
| DocID |
The DocID value of the document to add. |
Remarks
Not available in PowerWeb. This method is intended to be used in a custom command's Initialize event to add documents to a batch for processing.
AskConfirmation Method
Shows a confirmation prompt in the batch progress dialog with Yes and No radio buttons for answer selection and an optional comment field.
Syntax
AskConfirmation(ID As String, Label As String, [Default as AS_CONFIRMATION_DEFAULT_VALUE], [Comment As AS_CONFIRMATION_COMMENT_FLAGS])
| Name | Description |
|---|---|
|
ID |
Identifier for this confirmation prompt that can be used to refer to the user's answer. |
|
Label |
Text of the prompt. |
|
Default |
Default radio button. |
|
Comment |
Combination of flag values that determine whether comments are accepted and are mandatory or optional. |
Example
AskInput Method
Shows an input field in the batch progress dialog.
Syntax
AskInput(ID As String, Label As String, [Type as AS_INPUT_RESULT_TYPE], [Rule As AS_INPUT_VALIDATION_RULE], [Prototype As String])
| Name | Description |
|---|---|
|
ID |
Identifier for this input field that can be used to refer to the user's answer. |
|
Label |
Text of the field label. |
|
Type |
Optional value that represents the type of input that is accepted. |
|
Rule |
Optional value that represents the type of input validation performed. |
|
Prototype |
Optional name of an existing custom property from which to inherit the property's validation rules. |
Example
Confirmation Method
Shows a custom confirmation dialog. This method should not be confused with the Confirmation Property.
Syntax
Confirmation(ID As String)
| Name | Description |
|---|---|
|
ID |
Identifier of the content to show in the dialog. |
Return Value
Object with two properties, the user's input in Value and the user's comment (if any) in Comment.
Remarks
Learn how to create confirmation pages. You can also see examples of this functionality in this Knowledgebase article.
FailCurrent Method
Fail the current item in the current batch operation.
Syntax
FailCurrent([Message])
| Name | Description |
|---|---|
|
Message |
Append the specified message to the Comments property. |
Remarks
Use this method very carefully in managed change and Meridian Advanced Project Workflow operations, batch operations, or if references are involved. It could cause unexpected results.
For example, if a project copy is made of a master document that has a reference to another document and the operation is canceled by validation in script, the referenced document might still be copied but without the reference (because the master document was not copied). If the successful project copy is then released as a master revision, the existing reference between the source documents will be deleted (because the project copy had no reference to the master document).
In such scenarios, the validation script should produce a different result than aborting the operation, such as setting the target folder to Nothing, which prevents copying the referenced document.
Input Method
Shows the specified confirmation content.
Syntax
Input(ID As String) As Object
| Name | Description |
|---|---|
|
ID |
Identifier of the content to show in the dialog box. |
Return Value
Object with two properties, the user's input in Value and the user's comment (if any) in Comment.
Example
PrintDetails Method
Shows a string in the batch progress dialog box.
Syntax
PrintDetails(String As String)
| Name | Description |
|---|---|
|
String |
The text string to show in the progress dialog box. |
Remarks
To add a string to a the Comment log of a document, use the Document.Log method instead as described in Log method.
In Meridian 2021, event scripts such as this one do not work where focus is set on the folder level and a create a new document command for document type with wizard page (without template) is used.
1
2
3
Sub DocGenericEvent_BeforeNewDocument(Batch, Action, SourceFile, DocType, DocTemplate)
batch.PrintDetails "BeforeNewDocument"'(Document.FileName) 'Add your code here
End Sub
In this scenario, the document is created, but the focus remains on folder level and the navigation view is not refreshed. This will be fixed in a future release.
ShowInfo Method
Shows one or more lines of text with an optional heading in a confirmation dialog. The first 5 lines of text are visible by default with a vertical scroll bar if more lines exist.
Syntax
ShowInfo(Info As String, Heading As String)
| Name | Description |
|---|---|
|
Info |
Text of the information. |
|
Heading |
Text of the heading. |
