# Attach a Doc

This endpoint creates a copy of the Doc which was previously uploaded to temporary storage through the upload URL generated through the create_upload_url endpoint. The copy of the Doc is attached to the Twin and stored in the Twin's directory under the given "doc_name".

NOTE

In order to create a copy of the Doc and attach it to the Twin, the Doc needs to be already uploaded through the upload URL. The upload URL is returned in the response of the request sent to the create_upload_url endpoint.

Method Path Operation*
POST /twins/{twin}/docs attach_twin_doc

*

In order for a user to perform the "attach_twin_doc" operation, the "attach_twin_doc" permission must be included in the list of allowed actions in the statement of the user's role.

# Request

Parameter Type In Description
{twin}
required
string path Twin UUID.
doc_name
required
string body Name of the Doc. It must match the regular expression (opens new window) (^(?([a-za-Z0-9_-]{1,32}\/){0,5}([a-zA-Z0-9_-]{1,32})(.[a-zA-Z0-9]{1,8})?$. It must be unique in the context of the Twin.
hash
optional *
string body SHA-256 hash (opens new window).
handler
required
string body URL handler generated through the create_upload_url endpoint.
storage_class
required
string, value is "access_optimized" or "cost_optimized", DEFAULT=access_optimized body Storage class of the Doc:
- "access_optimized": Storage class for frequently accessed data.
- "cost_optimized": Storage class for automatic cost savings for less frequently accessed data.
Once the Doc has been copied and attached to the Twin, the "storage_class" cannot be changed.
description
optional **
dictionary body User defined key-value pairs:
- key: It must match the regular expression (opens new window) ^[a-z_][0-9a-z_]{0,63}$.
- value: JSON compliant value.
If no fields have been added, the "description" attribute will not be displayed.
For more details consult the description field section.

*

If the "hash" parameter is provided in the request, the method will check whether the hash provided by the User is equivalent to the hash generated for the Doc. If they do not match, a copy of the Doc will not be generated. Please note that the "status" of the Doc will have the value "copying" in the response to the request of attaching the Doc to the Twin (attach_twin_doc endpoint). The "hash_mismatch" status will be returned when retrieving the Doc (get_twin_doc endpoint).

**

If no attributes are provided in the request body of "description" ("description": {}), the response will return an empty dictionary ("description": {}).

If "description" with the value null is provided in the request body, the response will not return the "description" field.

If the request body does not contain "description", the response will not return the "description" field.

In our example, we attach three Docs to the Twin. Each of the Docs will contain a copy of the file which we have uploaded through the upload URL to temporary storage.

# Response

Attribute Type Description
creation_certificate object
Certificate generated automatically by the system upon sending a request to copy the Doc (attach_twin_doc endpoint). It cannot be modified after it has been generated.
Attribute Type Description
created_ts timestamp Time at which the Doc was created. Measured in seconds (to three decimal places) that have elapsed since the Unix epoch (opens new window).
creator string Account UUID of the Account creating the Doc.
hash * string SHA-256 hash (opens new window).
size integer Size of the Doc in bytes.
storage_class string, value can be "access_optimized" or "cost_optimized" Storage class of the Doc:
- "access_optimized": Storage class for frequently accessed data.
- "cost_optimized": Storage class for automatic cost savings for less frequently accessed data.
Once the Doc has been copied and attached to the Twin, the "storage_class" cannot be changed.
status string, value can be "copying", "ok", "error", or "hash_mismatch" Status of the Doc:
- "copying": The Doc is in the process of being copied.
- "ok": The copy of the Doc has been successfully generated. It is attached to the Twin and stored in the Twin's directory.
- "hash_mismatch": The "hash" provided in the request does not match the hash of the Doc. A copy of the Doc could not be generated.
- "error": An error occurred and a copy of the Doc could not be generated.
updated_ts timestamp Time at which the Doc was last updated. Measured in seconds (to three decimal places) that have elapsed since the Unix epoch (opens new window).
description dictionary User defined key-value pairs:
- key: It must match the regular expression (opens new window) ^[a-z_][0-9a-z_]{0,63}$.
- value: JSON compliant value.
For more details consult the description field section.

*

The "hash" attribute is only displayed in the "creation_certificate" if it was provided in the request to the attach_twin_doc endpoint.

# Response ('Doc already exists')

NOTE

If you try to create a Doc that already exists, you will receive the error message "error": 'Doc already exists.'" for this Doc in the response. However, the response itself will return the 201 Created status code. Please see the below example for more details.

In our example, we want to attach two Docs to the Twin with the Twin UUID 3f359a50-65e2-4252-ba96-6fda5fe7e14c:

  • The Doc with the name "Certifications/certification_2022_v1.txt". A Doc with the name "Certifications/certification_2022_v1.txt" is already attached to the Twin.
  • The Doc with the name "Certifications/certification_2022_v1_copy3.txt". There is no Doc with this name attached to the Twin yet.

The response returns the message "error": "Doc already exists." for the Doc "Certifications/certification_2022_v1.txt" which is already attached to the Twin and the details of the Doc "Certifications/certification_2022_v1_copy3.txt" that we have attached to the Twin. The status code of the response is 201 Created.

# Response ('No Doc uploaded through the upload URL')

NOTE

If you have not uploaded a Doc through the upload URL, but try to attach a Doc, you will receive the error message "error": "No Doc uploaded through the upload URL - check handler []." for this Doc in the response. However, the response itself will return the 201 Created status code (see example below).

In our example, we want to attach the Doc with the name "Certifications/certification_2022_v3.txt" to the Twin with the Twin UUID 3f359a50-65e2-4252-ba96-6fda5fe7e14c. We have previously sent a PUT request to the upload URL. However, we have not attached a file to that request.

The response is the error message "error": "No Doc uploaded through the upload URL - check handler []."

# Status codes

Requests to this endpoint result in generic status codes. For a comprehensive list of status codes, please consult the Status Codes section.

Status code Message Comment
201 Created If a Doc that you are trying to attach to the Twin is already attached to the Twin, you will receive the error: "error": "Doc already exists." for this Doc in the response.
If you have not uploaded a Doc through the upload URL, but try to attach a Doc, you will receive the error message "error": "No Doc uploaded through the upload URL - check handler []." for this Doc in the response.