Update a Parameter Set

Overview

PUT /rest/parameterSets/{id}

This endpoint is used to update the parameters of an existing Parameter Set. The parameters sent to this endpoint are not automatically validated. To validate a parameter set, use the “Validate a Parameter Set” or “Validate a Parameter Set By ID” endpoint before or after updating.

Partial Updates for Parameter Sets

This endpoint allows for partial updates of a parameter set. This means you don't need to send the entire object to make a change. You can update specific fields without affecting the others.

For instance, you can update just one or more of the following fields in a single request:

public: To change the visibility of the parameter set.
ownerId: To change the ownership.
parameters: To modify the individual parameters within the set.

Simply include the fields you wish to change in your request body; all other fields will remain as they are. This approach makes it easier and more efficient to manage your parameter sets.

Validation

The details of the parameters object have been intentionally omitted in this documentation. This endpoint does not perform validation on the incoming parameters object. The report parameters in the parameters object are directly saved to the database.

The validation of these parameters is performed when the parameter set is loaded on the screen or used in preparing a report.

There is a separate endpoint for validating a parameter set configuration.

To ensure the integrity and correct format of the parameters you are submitting, we highly recommend the following steps:

Get the Current Format: First, use the Get parameters endpoint to retrieve the current, valid format of the parameters object.
Modify and Validate: Update the retrieved format with your desired values. Update the IDs of entities if the source and target systems are different.
Validate Endpoint: Before submitting your request, use the Validate endpoint to check the validity of your updated parameters object on the target system. This step is crucial for preventing errors and ensuring your data is correctly processed.

Required Permissions

Admins can update all parameter sets.
Users can update only their own parameter sets.

Request

CODE

PUT <service_url>/rest/parameterSets/{id}

Parameters

Parameter	Type	Description	Required
id	String	The ID of the parameter set you want to update	Yes

Request Body

The request body must be a JSON object with the following structure:

JSON

{
  "public": Boolean, // Indicates if the parameter set is public
  "parameters": Object, // The parameters in JSON format
  "ownerId": String // The ID of the owner of the parameter set
}

Example Request Bodies

Full update:

JSON

{
  "public": false,
  "ownerId": null,
  "parameters": {
    "reportType": "statusDuration",
    "filterType": "project",
    "projectKey": "ITSAMPLE",
    "aggregationType": "tableList",
    "groupByFields": [
        "project",
        "date:year:created",
        "date:month:created"
    ],
    "averageDenominator": "nonNull",
    "multiVisitBehavior": "average",
    "timePeriod": "month",
    "statuses": [],
    "includeDeletedStatuses": true,
    "fields": [],
    "historyFields": [],
    "groups": [],
    "dbsMetrics": [],
    "assignees": [],
    "dateRangeField": "created",
    "startDate": "",
    "endDate": "",
    "trimHistoryStartDate": "",
    "trimHistoryEndDate": "",
    "calendar": "normalHours",
    "dayLength": "24HourDays",
    "pageSize": 10,
    "startIssueIndex": 0,
    "sortBy": "",
    "sortByDeleted": "",
    "sortDir": "desc",
    "filters": {
        "valueFilters": [],
        "hideEmptyRows": false
    },
    "outputType": "xls",
    "exportGroupByFields": [
        "project",
        "date:year:created",
        "date:month:created"
    ],
    "exportDateFormat": "",
    "exportDateTimeFormat": "",
    "exportEmptyValueToken": "hyphen",
    "exportDecimalSeparator": null,
    "exportCsvFieldSeparator": null,
    "exportValueQuotationMark": null,
    "viewFormat": "humanReadable",
    "visitCounts": false,
    "dataBars": false,
    "oneDimensionChartType": "pie",
    "twoDimensionsChartType": "stackedColumn",
    "dateChartType": "timeline",
    "oneDimensionChartPercentage": "off",
    "twoDimensionsChartPercentage": "off",
    "excludeCurrentState": false,
    "highlightsRules": []
  }
}

Partial update:

JSON

{
    "public": false
}

Example Requests

CODE

PUT https://tis.obss.io/rest/parameterSets/2710a694-ec07-4b68-b9f3-1be82fd3af10

Response

Response Structure

JSON

{
  "id": String, // The unique identifier of the parameter set
  "name": String, // The name of the parameter set
  "isPublic": Boolean, // Indicates if the parameter set is public
  "ownerId": String // The ID of the owner of the parameter set
}

Example Response Body

JSON

{
  "id": "2710a694-ec07-4b68-b9f3-1be82fd3af10",
  "name": "Parameter set From Rest",
  "ownerId": "5d2wqe63b7a11eas7f31cd27",
  "public": false
}

Response Codes

200 OK: Returns the details of the updated parameter set.
400 Bad Request: If the request body is invalid.
401 Unauthorized: If you do not have permission to update.
404 Not Found: If the requested parameter set does not exist.