Detach a Document by its KHUB ID - Fluid Topics - 3.7

Manage Map Attachments in Fluid Topics

Product
Fluid Topics
FT_Version
3.7
Category
Technical Notes

To detach a map attachment from a DITA map by its khubId, add the following lines to the FluidTopicsControlFile.xml file:

<?xml version='1.0' encoding='utf-8'?>
<controlFile>
<resources>
<resource>
<filePath>my_map.ditamap</filePath>
<instances>
<instance>
<filePath>version1.ditaval</filePath>
<attachments>
<attachment>
<isAttached>false</isAttached>
<khubId>$ATTACHMENT_KHUB_ID</khubId>
</attachment>
</attachments>
</instance>
</instances>
</resource>
</resources>
</controlFile>

Where:

  • resource
    • filePath expects the absolute path to the DITA map file in the archive used to upload the DITA map to Fluid Topics. It can be retrieved from the Metadata Journal, in the dita:mapPath field.
  • instance
    • filePath expects the absolute path to the DITAVAL file in the archive used to upload the DITA map to Fluid Topics. It can be retrieved from the Metadata Journal, in the dita:ditavalPath field.
  • attachment
    • isAttached expects the false value to detach the attachment from the DITA map.
    • khubId is the ID given to the file to detach by the Fluidtopics connector. It is derived from the originId – or filepath if no originId was set – and the source. It is unique and can be retrieved by using a web service or from the URL of the map attachment when it is opened in the Viewer page: http://mysite.fluidtopics.net/viewer/book-attachment/$PUBLICATION_KHUB_ID/$MAP_ATTACHMENT_KHUB_ID

It is necessary to create one instance element for each DITAVAL variant:
- It is possible to provide more instances, and declare the map attachment only once for all of them.
OR
- It is possible to provide the instance only once, and then declare all attachments.
See the following section for use examples.

If a map attachment was added to a map using the legacy (mapping.json) method, you must use its khubId to detach it with the new Control File method.

The attachment is not deleted in case it would be attached to another document in the portal. It is only detached from the document. All its related information (originId, khubId, displayName, and so on) are stored for any further use.

Example

The Animals DITA map has the file pufferfish.pdf file, in its two instances, Novice and Intermediate.

To detach goldfish.png from the Animals DITA map, in its Novice instance, one possibility is to use its khubId.

When the goldfish attachment from the map is opened in the Viewer page, you can retrieve its khubId from the URL of the page: http://mysite.fluidtopics.net/viewer/book-attachment/3b5d1zP9~WhIcoVsGwdiZg/vQlcqgYveKfDv53M5zn82Q

The following lines are added to the FluidTopicsControlFile.xml file to detach the image from the Novice instance of the Animals DITA map:

<controlFile>
<resources>
<resource>
<filePath>_animals.ditamap</filePath>
<instances>
<instance>
<filePath>Novice.ditaval</filePath>
<attachments>
<attachment>
<isAttached>false</isAttached>
<khubId>vQlcqgYveKfDv53M5zn82Q</khubId>
</attachment>
</attachments>
</instance>
</instances>
</resource>
</resources>
</controlFile>

Once published to Fluid Topics, the Goldfish image is not available anymore in the Attachments tab of the Novice instance of the Animals DITA map.

If both the FluidTopicsControlFile.xml and the FluidTopicsDitaControlFile.xml are found in a same archive, only the FluidTopicsControlFile.xml is taken into account. It generates the following error in the Back Office:

An other control file in the legacy format has been found in this archive (FluidTopicsDitaControlFile.xml), it will be ignored