Approval Flows and Change Requests
Learn how to manage change control on segments and feature flags programmatically using the Admin API.
Change control is critical to the success of any ongoing project and especially fundamental to software development. It is used to ensure that changes are introduced in a controlled and coordinated manner, reducing the risk of unnecessary changes and ensuring minimal disruption to services.
Harness FME supports change control on segment and feature flags objects. If change control is enabled in your environment, then API calls to modify these objects directly without creating a change request returns a 403 stating that Approvals are required, for example:
{
"code": 403,
"message": "Approvals are required. orgId=id-org-UUID envId=id-envronment-UUID",
"details": "",
"transactionId": "22ugt6f5igp"
}Prerequisites
Install cURL. This application is a free HTTP API client that we will use to make API calls in this document. It should be installed already if you are on a Mac or a Linux machine. If you are more comfortable with other ways to call HTTP endpoints or other HTTP clients, you should be able to follow along. It is a command line tool, so you need to have basic familiarity with the CMD.exe command prompt on Windows or Terminal emulators on Mac or Linux machines.
You need a Harness API key, or a Service Account Token (SAT), to authenticate these calls.
Create a service account
To create an API key:
Create a service account at the Account Settings, Organization Settings, or Project Settings scope under Access Control, depending on how broadly this key needs to reach.
Under that service account, create an API key and generate a token.
Copy the token once it is generated. It is displayed only once.
Choose an authentication header
Requests to api.split.io accept two authentication headers:
x-api-key: The standard header used across Harness APIs, including Harness FME. This is the recommended header for new integrations, and the one used in the examples on this page.Authorization: Bearer: The legacy header used by earlier Split integrations. It is still fully supported, so existing scripts do not need to change.
Both headers authenticate the same token; use whichever fits your existing code:
To use this key for approving change requests, you need to first set this API key as an approver by following these steps:
In Admin settings, click Projects.
Find the project in which you want to set the API key as an approver. Click the View link in the Actions column.
Find the environment in which you want to set the key as an approver. Click the Edit link in the Actions column.
On the Edit Environment page, select Require approval for changes.
If you select:
Let submitters choose their own approvers, the API cannot be used to approve change requests, but it can still create them and set user account email addresses as approvers.
Restrict who can approve, you must explicitly select the API key as an approver.
Click Save. The next screen shows that the environment requires approvals.
For both of the following sections, we also need the project ID and environment ID. Those can be collected from the Harness FME user interface or from API calls.
Using our API key, we can call to the Workspaces endpoint (used for projects) as follows:
To retrieve our list of projects and their IDs:
Then, using that project ID, we can get the environments:
This returns the following data:
To do this using the user interface, go to Admin settings and select Projects to see the project names and IDs.
Click the View link in the Actions column to see a project's environment names and IDs.
Change requests with segments
Adding keys to a segment
Creating a segment in a project
Removing keys from a segment
Adding an initial empty segment definition to an environment
Updating segment tags
Updating segment owners
Updating segment descriptions
Removing an empty segment definition from an environment
Deleting a segment
Creating or deleting segment keys via the Admin API both require a HTTP POST request. All change requests go to the changeRequest endpoint. Before submitting the change request, you must gather the data required.
Segment Operation Payload
segment.name
The name of the segment being updated.
segment.keys
The segment keys to use as part of the operation.
operationType
The type of operation to perform (see operationType Values).
title
The title of the change request.
comment
Any change request comments.
approvers
Email address(es) of the approver(s). Cannot be the API key. See notes below.
scheduledFor
Optional. Unix timestamp in milliseconds marking the exact date and time the approved change request executes. This is an absolute point in time and does not change based on scheduledForTimezone. See Schedule a change request.
scheduledForTimezone
Optional. IANA time zone, such as America/Los_Angeles, used only to display scheduledFor in the Harness FME UI. It does not affect when the change request executes. Defaults to UTC if omitted.
operationType Values
CREATE
Add the keys to the segment.
ARCHIVE
Remove the keys from the segment.
Approvers Behavior by Environment Setting
Let submitters choose approvers
Provide email address(es) of desired approver(s).
Restrict who can approve
Leave the approvers array empty. The environment defines approvers.
In the following scenario, we plan on adding the segments San Francisco and Clark's Mountain to our segment beta_accounts. This object will look like the following:
Then, the call to create the change request will look like the following:
The result shows the successful creation of the change request:
To confirm this change request, we can call the GET request on the changeRequests endpoint:
We then see the REQUESTED status change request:
The GET supports pagination using nextMarker and previousMarker as optional query parameters. It also is possible to also get APPROVED, REJECTED, WITHDRAWN, and PUBLISHED change requests using the status query parameter.
In the Harness FME user interface, we can also confirm the pending change request exists when you see the message This segment has pending change. View the change.
At this point, if the API key is not set as an approver, the only other thing we can do with it is withdraw the change request.
Now if we call the GET request like we did previously, you won’t see the change request.
This call returns the following:
To see a withdrawn change request, use this endpoint to see a single change request. To do this, we need to put the change request ID into the endpoint URL:
This returns the change request showing the WITHDRAWN status. Notice the comments objects at the bottom also showing the history of comments as well. In the case of change request management, it is helpful to have meaningful comments.
Another way to see this is to explicitly call to list all WITHDRAWN change requests.
If the Admin API is set as an approver, you can approve the change request by setting the status to APPROVED instead of WITHDRAWN as shown below:
The status changes to PUBLISHED if the change request is successfully approved.
It is important to note that you cannot use the same API key to submit and approve the same request. In that scenario you would need two API keys. One API key to submit requests and the other set up as an approver.
Change requests with feature flags
Change requests with feature flags have a few more options than change requests with segments.
Changing a feature flag definition in an environment
Creating a new feature flag in a project
Adding a feature flag definition to an environment
Updating feature flag tags
Removing a feature flag definition from an environment
Updating feature flag owners
Killing or reactivating a feature flag
Updating a feature flag description
Updating a feature flag rollout status
Deleting a feature flag with no targeting rules
The same changeRequest endpoint is used for feature flag change requests. However, the object sent in the body of the request is different.
We need to gather the following information to build the object to send:
Feature Flag Operation Payload
split
The feature flag definition object. Use a GET call on the feature flags endpoint to retrieve the existing definition.
For KILL, RESTORE, or ARCHIVE operations, only split.name is required.
For UPDATE and CREATE operations, the full feature flag definition is required.
operationType
The type of operation to perform (see operationType Values).
title
The title of the change request.
comment
Any change request comments.
rolloutStatus.id
The rollout status ID. Not required for KILL operations.
approvers
Email address(es) of the approver(s). Cannot be the API key. See Approvers Behavior.
scheduledFor
Optional. Unix timestamp in milliseconds marking the exact date and time the approved change request executes. This is an absolute point in time and does not change based on scheduledForTimezone. See Schedule a change request.
scheduledForTimezone
Optional. IANA time zone, such as America/Los_Angeles, used only to display scheduledFor in the Harness FME UI. It does not affect when the change request executes. Defaults to UTC if omitted.
operationType Values
KILL
Kill the feature flag, resulting in only the default treatment being served.
RESTORE
Restore a killed feature flag.
UPDATE
Update the treatment definition of the feature flag.
CREATE
Create a new feature flag.
ARCHIVE
Remove the feature flag definition from the environment.
Approvers Behavior by Environment Setting
Let submitters choose approvers
Provide email address(es) of desired approver(s).
Restrict who can approve
Leave the approvers array empty. The environment defines approvers.
For this exercise, you are going to take an existing feature flag definition and create a new, different feature flag called copy_of_onboarding_flow with the rollout percentage changed from 50/50 to 80/20 on/off.
The feature flag we are using is called new_onboarding_flow.
In the Harness FME user interface, the default rule shows a 50/50 rollout:
The first thing we need to do is to create the project level feature flag in order to add a feature flag definition to our environment. This call creates the new feature flag with a simple description.
You don’t need the feature flag id here so just having a successful result of the API call will be sufficient.
Rather than trying to create the feature flag definition object we want from scratch, it’s much easier to retrieve the existing feature flag object and make the necessary modifications.
As such, we first get the feature flag definition.
The returned value is the full feature flag definition with ID, name, environment, and trafficType along with the treatment definitions. However, for what you need, you can ignore that. The properties we need are the ones below that are returned.
name
Feature flag name.
treatments
Name and description of treatments.
defaultTreatment
Name of default treatment.
trafficAllocation
0-100, percentage of traffic allocated to the feature flag.
rules
Targeting rule objects.
defaultRule
Default targeting rule.
Now that we have our feature flag object, we are going to change the defaultRule object to give the on treatment a size of 80 and the off treatment a size of 20. The object now looks like the following:
The other piece of information that we need is the rollout status we want to use. Getting the rollout status ids can be done with this HTTP GET request.
This returns the rollout statuses. In our case, we are interested in the Ramping status.
Putting this object into our change request would look like the following:
With our object created and information gathered, now you can submit this as a CREATE change request.
The returned value shows the change request and the change request ID.
As with segments change requests, Harness FME doesn’t allow for the same API key or user to approve a change request that it submitted. This can be approved either by a different Admin API Key or by a user manually.
Once approved, let’s say we want to update the feature flag to a 90/10 rollout. You need to create a change request of operationType UPDATE. The only difference between UPDATE and CREATE is that UPDATE operations act upon existing feature flag definitions.
For example, this is an UPDATE call to update the existing feature flag we created to a new rollout percentage.
The Admin API can also be used for creating change requests to kill a feature flag. For this, you don’t need the feature flag definition, only the feature flag name.
You would kill the feature flag in the case of alerts showing performance problems, for example:
The response shows the proposed feature flag definition with a split.killed property equal to true.
This same API call can be used to create a change request to RESTORE the killed feature flag to its state before the kill or ARCHIVE the feature flag to remove it from the environment entirely just by changing the operationType object property.
Schedule a change request
By default, an approved change request executes immediately. To defer execution, include scheduledFor in the request body when you submit the change request. scheduledFor is a Unix timestamp in milliseconds marking the exact date and time the change executes. This applies to change requests for both segments and feature flags.
Optionally, include scheduledForTimezone to control the time zone used to display that scheduled date and time in the Harness FME UI, for example to approvers reviewing the pending change. scheduledForTimezone does not shift the instant that scheduledFor represents; it only affects display. If omitted, Harness FME displays the scheduled time in UTC. The value must be a valid IANA time zone identifier, such as America/New_York or Europe/London; invalid time zones are rejected.
For example, this UPDATE change request schedules the rollout change for a future date and time:
Status lifecycle for scheduled change requests
A change request submitted with scheduling follows a different status lifecycle than a standard change request. The action you take to approve it is the same in both cases; only the status Harness FME reports back differs:
Submitted
REQUESTED
SCHEDULE_REQUESTED
Approved
APPROVED
SCHEDULED
Executed
PUBLISHED
PUBLISHED
A pending scheduled change request returns "status": "SCHEDULE_REQUESTED" instead of "status": "REQUESTED". Approve a scheduled change request the same way you approve a standard one: send a PUT request with "status":"APPROVED" in the body. Harness FME then reports the change request's status as SCHEDULED, not APPROVED, and it remains SCHEDULED until the scheduled time arrives, at which point it executes and moves to PUBLISHED.
Troubleshooting
See also
Last updated
Was this helpful?