Copying Attachments

You can use persistent.copyAttachments or persistent.copyAttachmentsLazy to copy one or more attachments from a source location (a field in a document) to a target location (A field in either the same document or a different document).
- persistent.copyAttachments: Executes the copy operation immediately when the script runs.
- persistent.copyAttachmentsLazy: Stages the copy operation to be executed later, after the script has finished running. This is useful for operations that don't need to happen instantly or are part of a larger sequence of lazy changes.

For attachments from the V1 documents the function: persistent.copyAttachmentsLazyV1 or persistent.copyAttachmentsV1 can be used.

Syntax

persistent.copyAttachments(copyOperationsArray);
persistent.copyAttachmentsLazy(copyOperationsArray);

Parameters

Both functions take a single parameter, which must be an array of objects containing at least one object. Each object in the array specifies one copy operation using the V1 format and both will be explained below per object. First the source object after that the target.

Source Parameter Details

This is the source where the current attachment stands which should be copied.

Parameter	Type	Required	Description
source	Object	Yes	An object defining the source attachment(s) to copy. Contains the following properties:
source.ddName	String	Yes	The document definition name of the source document.
source._id	String	Required (if externalId is not provided)	The ID of the source document.
source.externalId	String	Required (if _id is not provided)	The external ID of the source document.
source.valuePath	String	Yes	The path within the source document pointing to the attachment field.
source.fileNames	Array of Strings	Optional	List of specific filenames within the source field to copy.
source.fileIds	Array of Strings	Optional	List of specific file IDs within the source field to copy.

Target Parameter Details

Target object where the attachment will be copied to.

Parameter	Type	Required	Description
target	Object	Yes	An object defining the destination for the copied attachment(s). Contains the following properties:
target.ddName	String	Yes	The document definition name of the target document.
target._id	String	Required (if externalId is not provided)	The ID of the target document.
target.externalId	String	Required (if _id is not provided)	The external ID of the target document.
target.valuePath	String	Yes	The path within the target document where the attachment should be copied to.
target.clearField	Boolean	Optional	If set to true, the target field will be cleared of existing attachments before copying. Defaults to false.

Return value

Does not return anything, undefined.

Example

Copy attachment using both methods

The following example shows how to copy an attachment from a field in a 'source_document' to a field in a 'target_document' using either copyAttachments or copyAttachmentsLazy:

// To execute immediately:
const added = persistent.copyAttachments([
  {
        source: {
        ddName: serverDocument._documentDefinitionName,
      _id: serverDocument._id,
      valuePath: 'picture',
      fileNames: ['report.pdf', 'image.png'], // Copy only these files
      clearField: true // Clear the target field first
    },
    target: {
      ddName: serverDocument._documentDefinitionName,
      _id: serverDocument._id,
      valuePath: 'pictures',
    }
  }
]);

// To execute lazily after the script:
persistent.copyAttachmentsLazy([
  {
    source: {
      ddName: 'source_docs',
      externalId: 'SRC-EXT-001',
      valuePath: 'attachments.mainFile'
    },
    target: {
      ddName: 'target_docs',
      externalId: 'TARGET-EXT-001',
      valuePath: 'attachments.copiedFile'
    }
  }
]);

Copy using valuePath

Since this method is changed from V1 LineName or LineId is no longer supported.

Below shows the example on to add it to field 'ingredients' spot number one in line 'picture':

const added = persistent.copyAttachments([
  {
        source: {
        ddName: serverDocument._documentDefinitionName,
      _id: serverDocument._id,
      valuePath: 'picture',
      fileNames: ['report.pdf', 'image.png'], // Copy only these files
      clearField: true // Clear the target field first
    },
    target: {
      ddName: serverDocument._documentDefinitionName,
      _id: serverDocument._id,
      valuePath: 'ingredients.1.picture',
    }
  }
]);