This web service adds (if new) or updates (if existing) map attachments based on metadata selection.
- This web service is only available to users or API keys with the
ADMIN,KHUB_ADMIN, orCONTENT_PUBLISHERrole. - Users or API keys with the
CONTENT_PUBLISHERrole can only add or update a map attachment for a document published through a source they have permissions for. - It is necessary to define user credentials in the HTTP header when calling this web service.
| Method | Endpoint |
|---|---|
PUT |
|
| Query string parameter | Type | Required? | Description |
|---|---|---|---|
metadata=value |
String | Yes | Any metadata key-value couple defining the maps to add or update. For example, /api/admin/khub/documents/attachments?Version=Latest adds the same attachment(s) to all maps with the Version=Latest metadata key.Use an ampersand ( &) to make the request more precise by adding metadata keys. For example: /api/admin/khub/maps/attachments?Category=Example&Version=LatestTo target a single map, use the document's ft:originId value. |
It is necessary to provide an Ft-Calling-App value when using Fluid Topics web services. See Fluid Topics calling app.
To add or update a map attachment, the web service call requires a multipart/form-data request body where the different parts consist in:
-
Sending an order to the Fluid Topics server to attach a file to the matched publications.
This requires the upload of an
order.jsonfile containing the attachment's metadata. -
Uploading the attachment itself.
Example
The following code block is an example of order.json file for attaching a document:
{
"attachments": [
{
"id": "my_attachment",
"filename": "oleandor.jpeg",
"displayName": "Oleandor Company Logo"
}
]
}
| Field | Type | Description |
|---|---|---|
id |
String | The optional value used to identify the attachment (uses the filename by default). |
filename |
String | The file name of the map attachment. |
displayName |
String | The optional display name of the map attachment (uses filename by default). |
The web service is sending asynchronous requests. It may take a while for the attachment to upload, and for the publication to update.
Updating existing attachments requires calling the same web service with the same id (or filename if the id has not been specified), and by modifying the other properties (the displayName, attachment content, the filename if an id has been specified, or the content-type using the multipart request).
| Return code | Description |
|---|---|
202 ACCEPTED |
The update instruction was sent to the Fluid Topics processing pipeline. |
400 BAD REQUEST |
Invalid query. |
It is recommended to use the Add or update attachment web service over the map attachment web service.