Package Instructions

This page explains the use of the Instruction file ‘package-instruction.json’ when uploading packages to Dam.

• For general information about packages, see Packages in the Administrator Guide
• For more information how to define a package definition in System, see Package configuration 
• For an example of a package, see the User guide on Packages

In Dam, an instruction file is used by the Creative Cloud Connector to create publication item links to Dam files at check in. Often, images placed on the InDesign document are already present in Dam. Downloading and uploading those images causes unnecessary traffic. Adding instructions solves this issue and makes it unnecessary to upload the linked Dam files inside the package.

You can use this instruction file when you send packages to Dam that contain the exact same files that are already in Dam. With the instruction file you can create publication item links as well as record links between the masterfile in your package and linked Dam files.

• For more information see the Creative Cloud Connector Guide 
• For more information about publication item links, see Publication Item Links in the Administrator Guide.
• For more information on the Record link and the Record list field, read about those data types and their Data type specific information in the page Field definitions.

When working on a Dam InDesign document using the Creative Cloud Connector, it is unnecessary to download the placed Dam images and upload them again as part of a package, since these files are already in DAM. Instead, an instruction file, included in the package, is used to recreate the links at check-in.

Example
A user uploads a standard IsDesign package into Dam, which is unpacked into a record with the InDesign file as the masterfile with publication items.
A creative user working in InDesign, checks out this masterfile from Dam, using the Creative Cloud Connector. The creative user works on the InDesign file and checks it back into Dam, recreating the package at check-in. The placed files are not included in the package. Instead, an instruction file “package-instruction.json” is automatically added to the package by the Connector. In this JSON file, instructions are written to create publication item links to the placed files.
When the check in is done, the package is unpacked: the InDesign file is added as a new file version to the same record. The placed files are linked to the file version as publication items.

While the Creative Cloud Connector uses the instruction file to create publication item links, you can also create instructions to create record links.

To replace the actual files, place a file called package-instruction.json in the root folder of your package.

In this instruction file, refer to the file versions you want to link to your package’s Masterfile as publication items. To make sure the uploaded package is processed correctly and can be downloaded from Dam, add a file path to the referenced content in the instructions.

Example

{
  "instructions": [
    {
      "fileVersionId": "d720224b-981b-40af-8a87-ab8f0095e98b",
      "path": "/NameOfMyFolder/Links/FileName_01.psd",
      "type": "pubItem"
    },
    {
      "recordId": "95354bd5ea9d4977a24dab8f0095bddd",
      "path": "/ NameOfMyFolder/Related/FileName_02.pdf",
      "type": "recordLink",
      "linkField": " linkField "
    }
  ]
}

Attributes

The attributes for publication items are:

• type: pubItem
• fileVersionId: guid
• path: The relative path of the file when it would have been physically part of the package. This path will be used to reconstruct the package in the action Download Package.

The attributes for record links are:

• type: recordLink
• linkField: name of your record link field or record list field
• recordId: guid
• path: The relative path of the file when it would have been physically part of the package. This path will be used to reconstruct the package in the action Download Package.

After the package upload, the new masterfile contains links to the Dam content that is referenced in the instructions.

To have your files successfully linked, make sure the instruction file and the package system setting .packageIngestion are configured correctly.
For information on how to define the package system setting in System correctly, see Package configuration.

• The instruction file:
  • is placed in the root folder of your package
  • the name is: package-instruction.json
• The package system setting .packageIngestionConfiguration is correctly configured
  • there should be a package setting that identifies the package type of your package. See Identifying the package type.
  • this package type setting is enabled.
  • the result of the regex that identifies which files become linked records matches the file path in the instruction file. See Linked records.
    

    <records>
            <add regex="links\\(.*?)$" linkType="recordLink" linkField="FD RecordLink One2Many" checkDuplicate="true">
              <classification type="namePath" value="Flying Dutchmen" />
            </add>
    </records>

You can see that files are linked by instructions in the file version’s manifest:
For more information, see the manifest section on the package upload page in the Administrator Guide.

<file path="\NameOfMyFolder\Links\FileName_01.psd">
        <placements>
          <placement fileName="FileName_01.psd" type="PubItem">
            <record state="frominstruction" id="95354bd5-ea9d-4977-a24d-ab8f0095bddd" />
            <fileVersion id="d720224b-981b-40af-8a87-ab8f0095e98b" /> </placement> </placements> </file>

There can be a conflict between the instruction file and the package setting:

• File path When the path does not match any records regex in the configuration, the file is ignored.
• Linktype or LinkField: the definition in the instructions prevails.
  • e.g. when the package setting defines the files in a folder to become publication items and the instruction file defines these files to become Record list fields, the files will become Record list fields.