Propagation rules


Identity propagation rules

Identity propagation rule entities represent a unidirectional provisioning relationship between a subset of identities on a source identity store and a target identity store. Rules contain attribute mappings, which must be added manually. The PingOne API does not include the default attribute mappings defined by each identity store automatically.

The examples that follow show common actions to find and manage identity propagation rule resources. You need the Environment Admin role to perform operations on identity propagation rule entities.

Propagation rule API operations

The propagation rule endpoints support the following operations:

For hands-on experience with the propagation rule API endpoints, click the Run in Postman button below to download a Postman collection that you can import and open in your local Postman application.

Propagation rule data model

Property Description
active A boolean that specifies whether this rule is active.
environment.id A string that specifies the environment resource’s unique identifier associated with the resource.
id A string that specifies the resource’s unique identifier.
name A string that specifies the name of the propagation rule. This is a required property.
plan.id A string that specifies the plan ID associated with this rule. This is a required property.
populations.id An array that specifies the list of population IDs to which this rule applies. This is a required property.
sourceStore.id A string that specifies the ID of the source store to which this rule applies. This is a required property.
targetStore.id A string that specifies the ID of the target store to which this rule applies. This is a required property.

Propagation rule mappings data model

Property Description
environment.id A string that specifies the environment resource’s unique identifier associated with the resource.
id A string that specifies the resource’s unique identifier.
sourceAttribute A string that specifies the source attribute for the rule mapping. This is a required property.
targetAttribute A string that specifies the target attribute for the rule mapping. This is a required property.

Response codes

Code Message
200 Successful operation.
201 Successfully created.
204 Successfully removed. No content.
400 The request could not be completed.
401 You do not have access to this resource.
404 The requested resource was not found.

Endpoint examples

Get propagation rules

The GET /environments/{environmentId}/propagation/rules endpoint returns a list of all propagation rule resources associated with the specified environment resource.

curl -X "GET" "https://api.pingone.com/v1/environments/{environmentId}/propagation/rules" \
-H 'Authorization: Bearer jwtToken'

The response data looks like this:

{
  "_embedded": {
    "rules": [
      {
        "plan": {
          "id": "8c9cc5b2-4171-4804-abd4-115a8948e453"
        },
        "sourceStore": {
          "id": "a6f91d1d-b50e-4c22-afd7-9491bf1edf07"
        },
        "targetStore": {
          "id": "407cfeb1-f81b-4ee6-838b-78e24e0ff92b"
        },
        "active": true,
        "populations": [
          {
            "id": "233c60bc-cd43-4f83-9fce-00e90d31bd16"
          },
          {
            "id": "122b60bc-cd43-4f83-9fce-00e90d31bd16"
          }
        ],
        "id": "86b88c9c-613d-4cdd-a0af-71d0dfba0c2f",
        "environment": {
          "id": "0d73e3ae-c424-42fd-ad71-9a1c79e90d06"
        },
        "_links": {
          "update": {
            "href": "https://api.pingone.com/v1/environments/0d73e3ae-c424-42fd-ad71-9a1c79e90d06/propagation/rules/86b88c9c-613d-4cdd-a0af-71d0dfba0c2f"
          },
          "get": {
            "href": "https://api.pingone.com/v1/environments/0d73e3ae-c424-42fd-ad71-9a1c79e90d06/propagation/rules/86b88c9c-613d-4cdd-a0af-71d0dfba0c2f"
          },
          "create": {
            "href": "https://api.pingone.com/v1/environments/0d73e3ae-c424-42fd-ad71-9a1c79e90d06/propagation/plans/a6f91d1d-b50e-4c22-afd7-9491bf1edf07/rules"
          },
          "delete": {
            "href": "https://api.pingone.com/v1/environments/0d73e3ae-c424-42fd-ad71-9a1c79e90d06/propagation/rules/86b88c9c-613d-4cdd-a0af-71d0dfba0c2f"
          }
        }
      }
    ]
  },
  "_links": {
    "self": {
      "href": "https://api.pingone.com/v1/environments/0d73e3ae-c424-42fd-ad71-9a1c79e90d06/propagation/rules"
    }
  }
}

Get one propagation rule

To get data for a single propagation rule resource, the GET /environments/{environmentId}/propagation/rules/{ruleId} operation returns data for the propagation rule resource with the specified ID.

curl -X GET "https://api.pingone.com/v1/environments/{environmentId}/propagation/rules/{ruleId}" \
-H "Authorization: Bearer jwtToken"

The response data looks like this:

{
  "plan": {
    "id": "8c9cc5b2-4171-4804-abd4-115a8948e453"
  },
  "sourceStore": {
    "id": "a6f91d1d-b50e-4c22-afd7-9491bf1edf07"
  },
  "targetStore": {
    "id": "407cfeb1-f81b-4ee6-838b-78e24e0ff92b"
  },
  "active": true,
  "populations": [
    {
      "id": "233c60bc-cd43-4f83-9fce-00e90d31bd16"
    },
    {
      "id": "122b60bc-cd43-4f83-9fce-00e90d31bd16"
    }
  ],
  "id": "86b88c9c-613d-4cdd-a0af-71d0dfba0c2f",
  "environment": {
    "id": "0d73e3ae-c424-42fd-ad71-9a1c79e90d06"
  },
  "_links": {
    "create": {
      "href": "https://api.pingone.com/v1/environments/0d73e3ae-c424-42fd-ad71-9a1c79e90d06/propagation/plans/a6f91d1d-b50e-4c22-afd7-9491bf1edf07/rules"
    },
    "self": {
      "href": "https://api.pingone.com/v1/environments/0d73e3ae-c424-42fd-ad71-9a1c79e90d06/propagation/rules/86b88c9c-613d-4cdd-a0af-71d0dfba0c2f"
    },
    "update": {
      "href": "https://api.pingone.com/v1/environments/0d73e3ae-c424-42fd-ad71-9a1c79e90d06/propagation/rules/86b88c9c-613d-4cdd-a0af-71d0dfba0c2f"
    },
    "delete": {
      "href": "https://api.pingone.com/v1/environments/0d73e3ae-c424-42fd-ad71-9a1c79e90d06/propagation/rules/86b88c9c-613d-4cdd-a0af-71d0dfba0c2f"
    }
  },
  "_embedded": {
    "mappingList": [
      {
        "id": {
          "environmentId": "0d73e3ae-c424-42fd-ad71-9a1c79e90d06",
          "modelId": "1fe0ec15-77a0-44a4-af34-3b9b66a69285"
        },
        "ruleId": "86b88c9c-613d-4cdd-a0af-71d0dfba0c2f",
        "sourceAttribute": "username",
        "targetAttribute": "userName",
        "modelId": "1fe0ec15-77a0-44a4-af34-3b9b66a69285",
        "environmentId": "0d73e3ae-c424-42fd-ad71-9a1c79e90d06",
        "_links": {
          "self": {
            "href": "https://api.pingone.com/v1/environments/0d73e3ae-c424-42fd-ad71-9a1c79e90d06/propagation/mappings/1fe0ec15-77a0-44a4-af34-3b9b66a69285"
          },
          "rule": {
            "href": "https://api.pingone.com/v1/environments/0d73e3ae-c424-42fd-ad71-9a1c79e90d06/propagation/rules/86b88c9c-613d-4cdd-a0af-71d0dfba0c2f"
          }
        }
      },
      {
        "id": {
          "environmentId": "0d73e3ae-c424-42fd-ad71-9a1c79e90d06",
          "modelId": "87df213e-b11f-4a17-aba3-9acfaff57406"
        },
        "ruleId": "86b88c9c-613d-4cdd-a0af-71d0dfba0c2f",
        "sourceAttribute": "email",
        "targetAttribute": "workEmail",
        "modelId": "87df213e-b11f-4a17-aba3-9acfaff57406",
        "environmentId": "0d73e3ae-c424-42fd-ad71-9a1c79e90d06",
        "_links": {
          "self": {
            "href": "https://api.pingone.com/v1/environments/0d73e3ae-c424-42fd-ad71-9a1c79e90d06/propagation/mappings/87df213e-b11f-4a17-aba3-9acfaff57406"
          },
          "rule": {
            "href": "https://api.pingone.com/v1/environments/0d73e3ae-c424-42fd-ad71-9a1c79e90d06/propagation/rules/86b88c9c-613d-4cdd-a0af-71d0dfba0c2f"
          }
        }
      }
    ]
  }
}

Get propagation rule mappings

To get information about the attribute mappings associated with a propagation rule resource, the GET /environments/{environmentId}/propagation/rules/{ruleId}/mappings operation returns data about the mapping attributes associated with the propagation rule specified by its ID.

curl -X GET "https://api.pingone.com/v1/environments/{environmentId}/propagation/rules/{ruleId}/mappings" \
-H "Authorization: Bearer jwtToken"

The response data looks like this:

{
  "_embedded" : {
    "mappings" : [ {
      "id" : "1fe0ec15-77a0-44a4-af34-3b9b66a69285",
      "environment" : {
        "id" : "0d73e3ae-c424-42fd-ad71-9a1c79e90d06"
      },
      "rule" : {
        "id" : "86b88c9c-613d-4cdd-a0af-71d0dfba0c2f"
      },
      "sourceAttribute" : "username",
      "targetAttribute" : "userName"
    }, {
      "id" : "87df213e-b11f-4a17-aba3-9acfaff57406",
      "environment" : {
        "id" : "0d73e3ae-c424-42fd-ad71-9a1c79e90d06"
      },
      "rule" : {
        "id" : "86b88c9c-613d-4cdd-a0af-71d0dfba0c2f"
      },
      "sourceAttribute" : "email",
      "targetAttribute" : "workEmail"
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api.pingone.com/v1/environments/0d73e3ae-c424-42fd-ad71-9a1c79e90d06/propagation/rules/86b88c9c-613d-4cdd-a0af-71d0dfba0c2f/mappings"
    }
  }
}

Create propagation rules

The POST /environments/{environmentId}/propagation/rules operation adds a new propagation rule resource to the specified environment resource.

curl -X "POST" "https://api.pingone.com/v1/environments/{environmentId}/propagation/rules" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d '{
  "name": "MyPropagationRule",
  "plan": {
    "id": "{planID}"
  },
  "sourceStore": {
    "id": "{sourceStoreID}"
  },
  "targetStore": {
    "id": "{targetStoreID}"
  },
  “populations”: [
      {
        "id": "{population1ID}"
      },
      {
        "id": "{population2ID}"
      }
    ]
  }'

Create propagation rule mappings

The POST /environments/{environmentId}/propagation/rules/{ruleId}/mappings operation creates a new propagation attribute mapping rule associated with the propagation rule specified by its ID.

curl -X GET "https://api.pingone.com/v1/environments/{environmentId}/propagation/rules/{ruleId}/mappings" \
-H "Authorization: Bearer jwtToken"
-d '{
    "sourceAttribute": "accountId",
    "targetAttribute": "userName"
}'

The response data looks like this:

{
  "id" : "7f7ad294-d5ef-4902-be8a-c980d9233493",
  "environment" : {
    "id" : "42a4cc8e-0d78-4505-a874-87d910254b18"
  },
  "rule" : {
    "id" : "5d67b932-b1cb-450d-853c-3f64314cedf6"
  },
  "sourceAttribute" : "accountId",
  "targetAttribute" : "userName",
  "_links" : {
    "get" : {
      "href" : "https://api-test.pingone.com/v1/environments/42a4cc8e-0d78-4505-a874-87d910254b18/propagation/mappings/7f7ad294-d5ef-4902-be8a-c980d9233493"
    },
    "create" : {
      "href" : "https://api-test.pingone.com/v1/environments/42a4cc8e-0d78-4505-a874-87d910254b18/propagation/rules/5d67b932-b1cb-450d-853c-3f64314cedf6/mappings"
    },
    "update" : {
      "href" : "https://api-test.pingone.com/v1/environments/42a4cc8e-0d78-4505-a874-87d910254b18/propagation/mappings/7f7ad294-d5ef-4902-be8a-c980d9233493"
    },
    "delete" : {
      "href" : "https://api-test.pingone.com/v1/environments/42a4cc8e-0d78-4505-a874-87d910254b18/propagation/mappings/7f7ad294-d5ef-4902-be8a-c980d9233493"
    }
  }
}

Update propagation rules

The PUT /environments/{environmentId}/propagation/rules/{ruleId} operation updates the property values of the identified propagation rule resource.

curl -X "PUT" "https://api.pingone.com/v1/environments/{environmentId}/propagation/rules/{ruleId}" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d '{
  "name": "MyPropagationRule",
  "plan": {
    "id": "{planID}"
  },
  "sourceStore": {
    "id": "{sourceStoreID}"
  },
  "targetStore": {
    "id": "{targetStoreID}"
  },
  “populations”: [
      {
        "id": "{population1ID}"
      },
      {
        "id": "{population2ID}"
      }
    ]
  }'

Delete propagation rules

The following sample shows the DELETE /environments/{environmentId}/propagation/rules/{ruleId} operation to delete the propagation rule resource specified by its ID in the request URL.

curl -X DELETE "https://api.pingone.com/v1/environments/{environmentId}/propagation/rules/{ruleId}" \
-H "Authorization: Bearer jwtToken"

When successful, the DELETE request returns a code 204 No Content message.