Attachments Transfer: User Guide

Table of Contents

When the connection is configured and the URL endpoint and API token are created, you can use the URL endpoint and API token to transfer attachments from the source instance (where the app is installed) to the target cloud instance. You can use these credentials either through Jira automation, or your own app.

Jira automation

Create a Jira automation on the desired trigger (e.g. Issue created) with the “Send web request“ action. Use the generated URL endpoint for the “Web Request URL“. To authenticate your API requests, include an Authorization header in each request. The value of this header should be the API token generated from the API Tokens in the Settings. See the “Send web request“ action example below:

• Web request URL

  • Fill with the generated URL endpoint, e.g.:

    • https://attachments-transfer-api.twinit.app/gateway/transferAttachments?id=aef469b5-34e5-4e16-942f-d3916d33b6b5

• HTTP method

  • POST

• Web request body

  • Custom data

    • jql (string) - (Required): The JQL query to find the target issue.

      • JQL has a limit of 10 issues per automation action!

    • sourceKey (string) - (Required): The key of the source issue.

    • commentId (string) - (Optional): The ID of the comment (if applicable):

      • If the commentId is included, only the attachments related to the specific comment will be sent. If the commentId is absent, all the issue attachments will be transferred.

      • You can use the {{issue.comment.last.id}} smart value to send the attachments attached to the last comment on the issue. If you need to send the attachment attached to the specific comment(s), use the specific commentId value(s) of the commentId instead of the smart value.

        • If the {{issue.comment.last.id}} smart value is added, you can also decide whether to create a comment (with the attachments links) or not. By default, the comment will be created on the target instance with the attachment links. If you don’t want to create a comment on the target instance, add createAsComment: false in the request body.

• Headers

The Automation action might look like this:

Open

After configuring the automation, the attachment will be sent to the target instance, based on the defined trigger(s).

Examples of the web request bodies for Jira automation

• Send all the attachments of the issue on a trigger to the issue ITSM-1 on the target instance:

• Send all the attachments of the source issue to the issues of the target instance, that are indicated in a custom field named “targetkeys“ of the source Issue:

• Send the attachment(s) of the last comment (without creating a comment) in the issue of the target instance, the key of which is written in the targetkey field of the source issue.

• Send all the attachments of the issue on a trigger to the issues ITSM-1 and ITSM-20 on the target instance:

• Send the attachment of the last comment in a trigger, creating a comment on a target cloud instance with the link to the attachment:

• Send the attachment of the last comment on a trigger, without creating a comment on a target cloud instance:

Send attachments to Assets

Based on various triggers, you can send the files attached to the issue to the Assets of the same or another instance. The files will be attached to the Asset objects as attachments:

To send files to the Asset objects, create a Jira automation on the desired trigger (e.g. Issue created) with the “Send web request“ action. Use the generated URL endpoint for the “Web Request URL“. To authenticate your API requests, include an Authorization header in each request. The value of this header should be the API token generated from the API Tokens in the Settings. See the “Send web request“ action example below:

• Web request URL

  • Fill with the generated URL endpoint, e.g.:

    • https://attachments-transfer-api.twinit.app/gateway/transferAttachments?id=aef469b5-34e5-4e16-942f-d3916d33b6b5

• HTTP method

  • POST

• Web request body

  • Custom data

    • aql (string) - (Required): The AQL query to find the target object.

      • You can use either specific object keys (e.g. Key IN (OBJ-1, OBJ-2)) or various Smart Values (see the instructions: automation smart values - Atlassian Support).

      • AQL has a limit of 10 objects per automation action!

    • sourceKey (string) - (Required): The key of the source issue.

    • commentId (string) - (Optional): The ID of the comment (if applicable):

      • If the commentId is included, only the attachments related to the specific comment will be sent. If the commentId is absent, all the issue attachments will be transferred.

      • You can use the {{issue.comment.last.id}} smart value to send the attachments attached to the last comment on the issue. If you need to send the attachment attached to the specific comment(s), use the specific commentId value(s) of the commentId instead of the smart value.

• Headers

After configuring the automation, the attachment will be sent to the Asset object of the target instance, based on the defined trigger(s).

Examples of the web request bodies for Jira automation for sending files to Asset

• Send attachment(s) of the source issue to the specific object (another instance), when the object key is known:

• Send attachments of the last comment of the source issue to several specific objects

  • When the object keys are initially known:

  • When the objects are selected in the Jira issue Assets field (A10) of the source instance (keys should be separated with commas):

• Send an attachment to a specific object (same or another instance) when the object name is known:

• Send an attachment to a specific object (same or another instance) when the object label is known:

• Send an attachment to an object (same or another instance) of the same name that is selected in the Assets field (Objects) of on the source instance:

• Send an attachment to an object (same or another instance) of the same label that is selected in an Assets field (Objects) of on the source instance:

• Send an attachment(s) of the last issue comment to objects of known schema ID (659) and Object Type ID (8059), when the object is selected in a field on a source instance (Objects). Attachemnt(s) will be sent to the objects with the same name as selected in the Assets field (Objects):

External application

Make a POST request with the generated URL endpoint. To authenticate your API requests, include an Authorization header in each request. The value of this header should be the API token generated from the API Tokens page. The sample request structure:

Parameters:

• jql (string) - (Required): The JQL query to find target issues.

  • JQL has a limit of 10 issues per automation action!

• sourceKey (string) - (Required): The key of the source issue.

• commentId (string) - (Optional): The ID of the comment (if applicable).

POST Request header

POST Request Body

curl example

Audit log

You can track all the requests in the Audit Log. To access the log, click the Audit log button on the “URL Endpoint” section of the settings:

Clicking the button will navigate you to the audit lot that shows the list of the requests:

A maximum of 20 log entries will be shown per single page.

You can filter the log by:

• Period

  • Anytime (shows all the available logs)

  • Today

  • Last 3 days

  • Last 7 days

  • Custom (select starting and the end dates)

• Status

  • All (shows request with all the statuses)

  • Success (shows successful requests)

  • Error (shows failed requests)

You can also search the entries by a search term. The field searched the entries by the URL endpoint name and Audit log ID.

After selecting the filters, click the “Search“ button to filter the log entries based on the selection.

For the request entries, the grid shows the following information:

• Date & time

  • When the request was sent

• Audit log ID

  • ID (order number) of the entry

• URL Endpoint

  • To which URL Endpoint the request was sent

• Status

  • Success or Error

• Operations

  • Clicking “Show more“ or anywhere on the entry row will expand the log details: