# Update an issue (CLI)

## Update an issue (CLI)

Updating an issue on the Errata Service through the CLI requires modifying the corresponding issue template or list of affected datasets on local files. In case of those files have been locally removed or compromised, users can easily retrieve fresh copies from the ES-DOC Errata server using the [retrieve](https://es-doc.github.io/esdoc-errata-client/retrieve_cli.html#retrieve) subcommand.

### Requirements

The new issue *.json* file is still constrained and validated against a new JSON schema. In fact, to guarantee the issue quality some attributes are immutable.

| Field          | Requirement                                              |
| -------------- | -------------------------------------------------------- |
| `uid`          | Mandatory and unchanged (between 16 and 255 characters)  |
| `title`        | Mandatory and unchanged (between 16 and 1023 characters) |
| `description`  | Mandatory and value-controlled                           |
| `mip_era`      | Mandatory and unchanged                                  |
| `severity`     | Mandatory and value-controlled                           |
| `status`       | Mandatory and value-controlled                           |
| `landing_page` | Optional                                                 |
| `materials`    | Optional                                                 |
| `dateCreated`  | Mandatory and unchanged                                  |
| `dateUpdated`  | Mandatory and unchanged                                  |
| `dateClosed`   | Not expected                                             |

<mark style="color:red;">**Warning:**</mark> safeguards requirements are:

* Empty attributes are disallowed.
* As a matter of fact updating the description is controlled by a variation threshold that should not be exceeded. Which is currently set at 20%, if the description is to be changed more than that, the issue should be closed and the creation of a brand new issue is required.
* All optional URLs must be valid (i.e., accessible).
* The issue status cannot change back to “new”.
* The creation date should not be modified in order to preserve an authentic set of records.
* The updated date is returned by the server.

<mark style="color:red;">**Note:**</mark> if a mistake occurred while declaring the issue, it should be reported to the [administrators](https://es-doc.github.io/esdoc-errata-client/credits.html#credits)).

Finally, feel free to remove, add or modify any dataset identifiers into the corresponding list if necessary as long as the dataset list isn’t empty. The life cycle of an issue may incorporate a few changes within the contents of an issue.

<mark style="color:red;">**Warning:**</mark> the `issue.json` needs to be at contain the same fields as in after the creation action. If your local file is corrupted consider using the [retrieve](https://es-doc.github.io/esdoc-errata-client/retrieve_cli.html#retrieve) subcommand to download a fresh copy. The issue json should always be conform to the templates otherwise an exception will be thrown.

### Modify the issue

From our previous issue template (see[ Create an issue (CLI)](/esgf-errata-service/errata-service-command-line-client/create-an-issue-cli.md)), we altered the description of the issue, the severity, the status status and added 2 new affected datasets. This will lead to updated files files as follows:

`issue.json`:

```
{
    "uid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "title": "Test issue title",
    "description": "This is a NEW test description, void of meaning.",
    "project": "cmip5",
    "severity": "critical",
    "materials": [
        "http://myerrata.com/images/before.jpg",
        "http://myerrata.com/images/after.jpg"
    ],
    "url": "http://websitetest.com/",
    "status": "onhold",
    "dateClosed": "YYYY-MM-DD HH:MM:SS",
    "dateUpdated": "YYYY-MM-DD HH:MM:SS"
}
```

`dataset.txt`:

```
cmip5.output1.IPSL.IPSL-CM5A-MR.historical.mon.land.Lmon.r1i1p1#20111119
cmip5.output1.IPSL.IPSL-CM5A-MR.historical.mon.land.Lmon.r2i2p2#20121212
cmip5.output1.IPSL.IPSL-CM5A-LR.historical.mon.land.Lmon.r3i1p1#20130514
cmip5.output1.IPSL.IPSL-CM5A-LR.piControl.mon.land.Lmon.r3i1p1#20130514
[...]
```

### Send the changes

The update subcommand has a similar structure as the creation command:

```
$> esgissue update --issue /path/to/issue.json --dsets /path/to/datasets.txt
```

On success the local issue file will be modified again. The update date will be modified accordingly:

```
{
    "uid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "title": "Test issue title",
    "description": "This is a NEW test description, void of meaning.",
    "project": "cmip5",
    "severity": "critical",
    "materials": [
        "http://myerrata.com/images/before.jpg",
        "http://myerrata.com/images/after.jpg"
    ],
    "url": "http://websitetest.com/",
    "status": "onhold",
    "dateClosed": "YYYY-MM-DD HH:MM:SS",
    "dateUpdated": "YYYY-MM-DD HH:MM:SS"
}
```

The updates now are registered both in the remote errata service and are reflected in the local issue files.

<mark style="color:red;">**Note:**</mark> The update operator can of course be used to close issues. This is a special case of update where the only field that is modified is the status into closed state.&#x20;


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://ipsl.gitbook.io/esgf-errata-service/errata-service-command-line-client/update-an-issue-cli.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.