# Update Policy Configuration

### Endpoints

```sh
PUT /api/private/lifecycle_management/policies/{policy_id}/versions/{version_number}
```

```sh
PATCH /api/private/lifecycle_management/policies/{policy_id}/versions/{version_number}
```

### Description

Update a specific version of an existing policy, including workflows, conditions, actions, and configuration settings. This endpoint allows you to modify the policy version's behavior and structure.

Use this endpoint to:

* Modify policy version workflows, conditions, and actions
* Update attribute transformers and lookup table references
* Adjust password complexity rules and mover properties
* Configure transformer functions for the policy version

{% hint style="warning" %}
Configuration changes to active policies take effect immediately. Consider testing changes in a draft policy first, or temporarily setting the policy to inactive during updates.
{% endhint %}

{% hint style="info" %}
**Version Number Usage**: You must update the specific version that is currently active or the version you want to modify. Use [Get Policy](/4yItIzMvkpAvMVFAamTf/developers/api/lifecycle-management/policies/getpolicy.md) to retrieve the `current_version_number` before making updates. You cannot create new versions through this endpoint; it only updates existing versions.
{% endhint %}

### API Reference

{% openapi src="/files/Aco9gj4MY2XoNiD4zIjr" path="/api/private/lifecycle\_management/policies/{value.policy\_id}/versions/{value.version\_number}" method="patch" %}
[openapi.yaml](https://1967633068-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MZDkWMxox3pekd0NsZJ%2Fuploads%2Fgit-blob-7fffa1b503c9e0990ac3091c19a420bf184d1dec%2Fopenapi.yaml?alt=media)
{% endopenapi %}

### Request Examples

#### Path Parameters

| Parameter        | Type    | Required | Description                                    |
| ---------------- | ------- | -------- | ---------------------------------------------- |
| `policy_id`      | string  | Yes      | Unique identifier of the policy                |
| `version_number` | integer | Yes      | Version number of the policy version to update |

#### Request Body

| Field         | Type   | Required | Description                                  |
| ------------- | ------ | -------- | -------------------------------------------- |
| `value`       | object | Yes      | The updated PolicyVersion object             |
| `update_mask` | object | No       | Field mask specifying which fields to update |

**PolicyVersion Object Fields**

| Field            | Type    | Required | Description                                                                  |
| ---------------- | ------- | -------- | ---------------------------------------------------------------------------- |
| `policy_id`      | string  | Yes      | ID of the policy this version belongs to                                     |
| `version_number` | integer | No       | Version number (output only)                                                 |
| `state`          | string  | No       | Version state: `DRAFT`, `PUBLISHED`, `RETIRED`                               |
| `config`         | object  | No       | Policy version configuration containing workflows, actions, and transformers |

**Configuration Object Details**

The `config` field contains the core policy version logic:

| Field                           | Type           | Description                                                              |
| ------------------------------- | -------------- | ------------------------------------------------------------------------ |
| `workflows`                     | array\[object] | Array of workflow objects that define when and how the policy triggers   |
| `actions`                       | array\[object] | Array of action objects that define what happens when conditions are met |
| `attribute_common_transformers` | array\[object] | Common attribute transformation rules                                    |
| `lookup_table_references`       | array\[object] | References to lookup tables used by the policy                           |
| `mover_properties`              | array\[string] | List of properties that, when changed, mark an identity as a "mover"     |
| `password_complexity_rules`     | array\[object] | Password complexity rules for sync operations                            |
| `transformer_functions`         | array\[object] | Custom transformation functions                                          |

### Response Examples

### Example Configuration

<details>

<summary>Complete Policy Configuration Example</summary>

The following example shows a complete policy configuration with workflows, conditions, and actions:

```json
{
  "workflows": [
    {
      "name": "Active Employees",
      "description": "Triggered when any active employee is active",
      "trigger_type": "TRIGGER_STRING",
      "trigger_string": "employment_status eq \"ACTIVE\"",
      "continuous_sync": true,
      "conditions_on_success": [
        {
          "name": "sync",
          "condition_type": "work_location eq \"China\"",
          "actions_to_run": [
            {
              "name": "ChinaEmployeeGroups",
              "type": "SYNC_IDENTITIES"
            }
          ]
        },
        {
          "name": "sync",
          "condition_type": "work_location eq \"US\"",
          "actions_to_run": [
            {
              "name": "UsEmployeeGroups",
              "type": "SYNC_IDENTITIES"
            }
          ]
        },
        {
          "name": "sync",
          "condition_type": "department eq \"Sales\" and manager eq true",
          "actions_to_run": [
            {
              "name": "SalesManagerGroups",
              "type": "SYNC_IDENTITIES"
            }
          ]
        }
      ]
    }
  ],
  "actions": [
    {
      "name": "UsEmployeeGroups",
      "description": "Adds US employees to defined access profiles",
      "type": "MANAGE_RELATIONSHIPS",
      "config": {
        "@type": "type.googleapis.com/lifecyclemanagement.v1.ManageRelationshipsActionConfig",
        "remove_existing_relationships": true,
        "access_profiles": ["<access_profile_id1>", "<access_profile_id2>"]
      }
    },
    {
      "name": "ChinaEmployeeGroups",
      "description": "Adds China employees to defined access profiles",
      "type": "MANAGE_RELATIONSHIPS",
      "config": {
        "@type": "type.googleapis.com/lifecyclemanagement.v1.ManageRelationshipsActionConfig",
        "remove_existing_relationships": true,
        "access_profiles": ["<access_profile_id3>", "<access_profile_id4>"]
      }
    },
    {
      "name": "SalesManagerGroups",
      "description": "Adds Sales Manager profiles",
      "type": "MANAGE_RELATIONSHIPS",
      "config": {
        "@type": "type.googleapis.com/lifecyclemanagement.v1.ManageRelationshipsActionConfig",
        "remove_existing_relationships": true,
        "access_profiles": ["<access_profile_id5>"]
      }
    }
  ],
  "attribute_common_transformers": []
}
```

**Configuration Structure Explanation**

**Workflows** define when the policy triggers:

* `trigger_string`: SCIM filter expression that determines when the workflow activates
* `conditions_on_success`: Array of conditions evaluated when the trigger is met
* `continuous_sync`: Whether to continuously monitor for changes

**Conditions** specify additional criteria:

* `condition_type`: SCIM filter expression for the specific condition
* `actions_to_run`: Actions executed when this condition is met

**Actions** define what happens when conditions are satisfied:

* `type`: Currently supports `MANAGE_RELATIONSHIPS` and `SYNC_IDENTITIES`
* `config`: Action-specific configuration object
* For `MANAGE_RELATIONSHIPS`: Defines access profiles to assign/remove

</details>

### Troubleshooting Common Issues

#### 404 Errors When Updating Policy Configuration

If you receive a 404 error when attempting to update a policy configuration, verify:

1. **Policy ID is correct**: Confirm the policy exists by first calling `GET /api/private/lifecycle_management/policies/{policy_id}`
2. **Version number exists**: Check the `current_version_number` from the GET response and ensure you're using the correct version
3. **Endpoint path is correct**: Ensure you're using `/versions/` (plural) in the URL path

**Common mistake**: Using `/version/{number}` instead of `/versions/{number}` in the endpoint path.

#### Policy Version Not Found

If you get errors about version not found:

* Always use the `current_version_number` from the [Get Policy](/4yItIzMvkpAvMVFAamTf/developers/api/lifecycle-management/policies/getpolicy.md) response
* Policy versions are auto-created and managed by the system - you can't create arbitrary version numbers
* If you need to work with a different version, you may need to publish or manage the policy state first

#### Configuration Validation Errors

When policy configuration updates fail validation:

1. **Check JSON structure**: Ensure your configuration object matches the expected schema
2. **Verify action types**: Confirm action `type` values are valid (e.g., `MANAGE_RELATIONSHIPS`, `SYNC_IDENTITIES`)
3. **Validate SCIM expressions**: Test trigger strings and condition strings for proper SCIM syntax
4. **Confirm referenced IDs**: Ensure access profile IDs and other references exist in your environment

#### Request Body Format

Ensure your request body follows this structure:

```json
{
  "value": {
    "policy_id": "your-policy-id",
    "config": {
      "workflows": [...],
      "actions": [...],
      "attribute_common_transformers": [...]
    }
  }
}
```

The configuration should be nested within a `value.config` object, not sent as the root object.


---

# 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://docs.veza.com/4yItIzMvkpAvMVFAamTf/developers/api/lifecycle-management/policies/updatepolicyconfiguration.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.