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.

{
  "jql": "issuekey = ITSM-1",
  "sourceKey": "{{issue.key}}",
  "commentId": "{{issue.comment.last.id}}",
  "createAsComment": true
}

• Headers

The Automation action might look like this:

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

The target and the source issue should not be the same. In this case, you will see the corresponding message in the audit log of the automation:

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:

{
  "jql": "issuekey = ITSM-1",
  "sourceKey": "{{issue.key}}"
}

• 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:

{
  "jql": "issuekey IN ({{issue.targetkeys}})",
  "sourceKey": "{{issue.key}}"
}

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

{
  "jql": "issuekey IN (ITSM-1, ITSM-20)",
  "sourceKey": "{{issue.key}}"
}

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

{
  "jql": "issuekey = ITSM-1",
  "sourceKey": "{{issue.key}}",
  "commentId": "{{issue.comment.last.id}}"
}

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

{
  "jql": "issuekey = ITSM-1",
  "sourceKey": "{{issue.key}}",
  "commentId": "{{issue.comment.last.id}}",
  "createAsComment": false
}

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.

{  
     "aql": "Key IN ({{issue.AssetField.key}})",
     "sourceKey": "{{issue.key}}",
     "commentId": "{{issue.comment.last.id}}"
}

• Headers

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

The target and the source issue should not be the same. In this case, you will see the corresponding message in the audit log of the automation:

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:

  {  
       "aql": "Key = OBJ-1",
       "sourceKey": "{{issue.key}}"
  }

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

  • When the object keys are initially known:

    {  
         "aql": "Key IN (OBJ-1, OBJ-2, OBJ-3)",
         "sourceKey": "{{issue.key}}",
         "commentId": "{{issue.comment.last.id}}"
    }

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

    {  
         "aql": "Key IN ({{issue.A10.key}})",
         "sourceKey": "{{issue.key}}",
         "commentId": "{{issue.comment.last.id}}"
    }

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

{  
     "aql": "name = \"Object Name\"",
     "sourceKey": "{{issue.key}}"
}

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

{  
     "aql": "label = \"Object Label\"",
     "sourceKey": "{{issue.key}}"
}

• 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:

{  
     "aql": "Key IN ({{issue.Objects}})",
     "sourceKey": "{{issue.key}}",
     "commentId": "{{issue.comment.last.id}}"
}

• 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:

{  
     "aql": "label in (\"{{issue.Objects}}\")",
     "sourceKey": "{{issue.key}}"
}

• 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):

{
  "aql": "objectSchemaId=659 and ObjectTypeId=8059 and label in (\"{{issue.Objects}}\")",
  "sourceKey": "{{issue.key}}",
  "commentId": "{{issue.comment.last.id}}"
}

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:

{
  "jql": {JQL_TO_FIND_TARGET_ISSUES}, //REQUIRED
  "sourceKey": {KEY_OF_SOURCE_ISSUE}, //REQUIRED
  "commentId": {ID_OF_COMMENT} //OPTIONAL
}

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

curl -H 'Authorization: 46f61f78-e138-4019-85a0-e239878f2c94'

POST Request Body

{
  "jql": "issuekey = ITSM-1",
  "sourceKey": "ITSM-15",
  "commentId": "12345"
}

curl example

curl --request POST \
  --url 'https://attachments-transfer-api.twinit.app/gateway/transferAttachments?id=aef469b5-34e5-4e16-942f-d3916d33b6b5 '
  --header 'Accept: application/json' \
  --header 'Authorization: 46f61f78-e138-4019-85a0-e239878f2c94'
  --data ' {
  "jql": "issuekey = ITSM-1",
  "sourceKey": "ITSM-15",
  "commentId": "12345"
}'