Editing a macro

Written by

Yandex Cloud

Updated at February 19, 2024

Request format
Response format

Use this request to edit macro parameters.

Request format

Before making the request, get permission to access the API.

To edit macro parameters, use an HTTP PATCH request:

PATCH /v2/queues/<queue_key_or_ID>/macros/<macro_ID>
Host: https://api.tracker.yandex.net
Authorization: OAuth <OAuth_token>
X-Org-ID: <organization ID>

{
  "name": "<macro_name>",
  "body": "<comment_text>\n{{currentDateTime}}\n{{issue.author}}",
  "fieldChanges": <object_or_array>
}

Headers

Host

Address of the node that provides the API:
```
https://api.tracker.yandex.net
```
Authorization

OAuth token in OAuth <OAuth_token> format, e.g.:
```
OAuth 0c4181a7c2cf4521964a72ff********
```
X-Org-ID or X-Cloud-Org-ID

Organization ID. You can find it out on the Tracker organizations page.
- If a Yandex 360 for Business organization is the only one linked to Tracker, the X-Org-ID header is used.
- If a Yandex Cloud Organization organization is the only one linked to Tracker, the X-Cloud-Org-ID header is used.
- If both Yandex 360 for Business and Yandex Cloud Organization organizations are linked to Tracker at the same time, the X-Org-ID header and the Yandex 360 for Business organization ID are used.

Resource

Parameter	Description	Data type
<queue_ID_or_key>	Queue ID or key. The queue key is case-sensitive.	String
<macro_ID>	Macro ID.	String

Request body parameters

Required parameters

Parameter	Value	Data type
name	Macro name.	String

Additional parameters

Parameter	Description	Data type
body	Message to be created when executing the macro in `<message_text>\n<variable>` format. Where: `<message_text>`: Text to be created in the Comment field when executing the macro. `\n`: Line break symbol. Variable that may contain: `{{currentUser}}`: Name of the user who ran the macro. `{{currentDateTime.date}}`: Macro execution date. `{{currentDateTime}}`: Macro execution date and time. `{{issue.<field_key>}}`: Key of the issue field to be displayed in the message. Full list of issue fields: https://tracker.yandex.ru/admin/fields To delete the message, use the construction `"body": {"unset":1}`	String
fieldChanges	Object or array with new settings for macro actions. The object structure may vary depending on the type of changes.	Object or array

Object structure fieldChanges

Add an action

Replace an action

Replace all actions

Remove an action

Add a macro action. Use the add parameter to add a field and its value to the list of available fields.

"fieldChanges": {
      "add": [
               {
          "field": "tags",
          "value": "tag2"
               },
                ...
              ]

Request body

Parameter	Description	Data type
fieldChanges	Object describing new settings of macro actions.	Object

Array object fieldChanges

Parameter	Description	Data type
add	Array describing the parameters of a new macro action.	Array

Array objects add

Parameter	Description	Data type
field	Issue field ID. Full list of issue fields	String
value	Value of the issue field.	String

Replace a macro action with a new one. Use the replace parameter to replace a field and its value, which are set using the target parameter, with new ones using the replacement parameter.

"fieldChanges": {
         "replace": [
                      {
                "target": {
                    "field": "tags",
                    "value": "tag2"
                          },
                "replacement": {
                    "field": "originalEstimation",
                    "value": "PT2H"
                                }
                        }
                      ]
}

Request body

Parameter	Description	Data type
fieldChanges	Object describing new settings of macro actions.	Object

Object parameters fieldChanges

Parameter	Description	Data type
replace	Array with action parameters to be replaced with new ones.	Array

Object array replace

Parameter	Description	Data type
target	Object with action parameters to be replaced.	Object
replacement	Object with new action parameters.	Object

Object parameters target and replacement

Parameter	Description	Data type
field	Issue field ID. Full list of issue fields	String
value	Value of the issue field.	String

Replace all macro actions with new ones. Only the fields and values specified in the array are retained.

"fieldChanges": [
                          {
             "field": "tags",
             "value": "tag2"
                          },
                          ...
]

Request body

Parameter	Description	Data type
fieldChanges	Object describing new settings of macro actions.	Object or array

Array parameters fieldChanges

Parameter	Description	Data type
field	Issue field ID. Full list of issue fields	String
value	Value of the issue field.	String

Remove a macro action. You can use the replace parameter to remove a field and its value.

"fieldChanges": {
         "remove": [
                    {
                  "field": "tags",
                  "value": "tag2"
                     },
                      ...
                    ]
}

Request body

Parameter	Description	Data type
fieldChanges	Object describing new settings of macro actions.	Object

Object field fieldChanges

Parameter	Description	Data type
remove	Array with information about the fields and values of the macro action to be removed.	Array

Array parameters remove

Parameter	Description	Data type
field	Issue field ID. Full list of issue fields	String
value	Value of the issue field.	String

Response format

Request executed successfully

Request failed

If the request is successful, the API returns a response with code 200 OK.

The response body contains a JSON object with all macro parameters, including the updated ones.

  {
    "self": "https://https://api.tracker.yandex.net/v2/queues/TEST/macros/3",
    "id": 3,
    "queue": {
      "self": "https://https://api.tracker.yandex.net/v2/queues/TEST",
      "id": "1",
      "key": "TEST",
      "display": "Test queue"
       },
    "name": "Test macro 1",
    "body": "Test comment\n{{currentDateTime}}\n{{issue.author}}",
    "fieldChanges": [
      {
        "field": {
           "self": "https://https://api.tracker.yandex.net/v2/fields/tags",
           "id": "tags",
           "display": "Tags"
          },
        "value": [
                "tag1"
                 ]
      },
       ...
    ]
  }

Response parameters

Parameter	Description	Data type
self	Address of the API resource with macro parameters.	String
id	Macro ID.	Number
queue	Object with information about the queue whose issues that the macro is applied to.	Object
name	Macro name.	String
body	Message to be created when executing the macro in `<message_text>\n<variable>` format. Where: `<message_text>`: Text to be created in the Comment field when executing the macro. `\n`: Line break symbol. Variable that may contain: `{{currentUser}}`: Name of the user who ran the macro. `{{currentDateTime.date}}`: Macro execution date. `{{currentDateTime}}`: Macro execution date and time.: `{{issue.field_key}}` Key of the issue field to be displayed in the message. Full list of issue fields: https://tracker.yandex.ru/admin/fields To delete the message, use the construction `"body": {"unset":1}`	String
fieldChanges	Array with information about the issue fields that the macro will trigger changes to.	Array of objects

queue object fields

Parameter	Description	Data type
self	Address of the API resource with information about the queue.	String
id	Queue ID.	String
key	Queue key.	String
display	Queue name displayed.	String

fieldChanges array objects

Parameter	Description	Data type
field	Object with information about the issue field.	Object
value	Array of issue field values.	Array of objects

field object fields

Parameter	Description	Data type
self	Address of the API resource with information about the issue field.	String
id	Issue field ID.	String
display	Issue field name displayed.	String

If the request is processed incorrectly, the API returns a response with an error code:

400: One or more request parameters have an invalid value.

403: Insufficient rights to perform this action. You can check what rights you have in the Tracker interface. The same rights are required to perform an action via the API and interface.

404: The requested object was not found. You may have specified an invalid object ID or key.

422: JSON validation error, the request is rejected.

500: Internal service error. Try resending your request in a few minutes.

503: The API service is temporarily unavailable.

Editing a macro

Request formatRequest format

Response formatResponse format

Was the article helpful?

Request format

Response format