--- title: Propagation Rules description: 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. component: pingone-api page_id: pingone-api:platform:identity-propagation-provisioning/propagation-rules canonical_url: https://developer.pingidentity.com/pingone-api/platform/identity-propagation-provisioning/propagation-rules.html section_ids: propagation-rule-data-model: Propagation rule data model outbound-ldap-configuration-data-object: Outbound LDAP configuration data object inbound-ldap-configuration-data-object: Inbound LDAP configuration data object propagation-synchronized-rule-data-model: Propagation synchronized rule data model additional-rule-data-models-by-request: Additional rule data models by request response-codes: Response codes --- # 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. | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | **Note:** To reflect the propagation rules API changes in the PingOne Admin Console, you must [create a new propagation revision](propagation-revisions/create-revision-1.html). | The PingOne Admin Console does display the default attribute mappings. When defining the connection in the Admin Console, if a rule does not have any user-defined mappings, the identity store's default mappings can be used. If at least one attribute mapping is defined in a rule, then all default mappings are ignored. 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. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | For known limitations when configuring rules, refer to [Known issues for provisioning through an LDAP gateway](https://docs.pingidentity.com/pingone/integrations/p1_provisioning_gateway_known_issues.html). | ## Propagation rule data model | Property | Type | Required? | Mutable? | Description | | ----------------------------------- | --------- | ----------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `active` | Boolean | Optional | Mutable | Whether this rule is active; defaults to `false`. | | `createdAt` | DateTime | N/A | Read-only | Date and time the propagation rule was created. | | `configuration` | Object | Required/Optional | Mutable | An [Outbound LDAP configuration data object](#outbound-ldap-configuration-data-object) is required for outbound LDAP Gateway stores (type `LdapGateway`). An [Inbound LDAP configuration data object](#inbound-ldap-configuration-data-object) is required for an inbound LDAP Gateway stores (where users user are provisioned into PingOne). Optional for all other cases and ignored if used. | | `deprovision` (deprecated) | Boolean | Optional | Mutable | Deprecated, use `managed` in [Propagation Stores](propagation-stores.html). Whether to enable deprovisioning of users for a store when it is deleted. The deprovisioning occurs when a new revision is created ([Create Propagation Revision](propagation-revisions/create-revision-1.html)). Not applicable on writeback rules and ignored if used. | | `description` | String | Optional | Mutable | Description of the propagation rule. | | `environment.id` | String | N/A | Read-only | Identifier (UUID) of the PingOne environment associated with the propagation rule. | | `groups` | Object\[] | Optional | Mutable | Array of objects, each of which contains the identifier of a group. | | `groups.id` | String | Required | Mutable | Identifier (UUID) of the group to include in this propagation rule. | | `id` | String | N/A | Read-only | Identifier (UUID) of the propagation rule. | | `name` | String | Required | Mutable | Unique name of the propagation rule. | | `parentRule.id` | String | Required/Optional | Immutable | Identifier (UUID) of the inbound propagation rule associated with this writeback propagation rule. Required for a writeback propagation rule, but should not be used with any other propagation rule. | | `plan.id` | String | Required | Immutable | Identifier (UUID) of the propagation plan associated with this propagation rule. | | `populationExpression` | String | Optional | Mutable | SCIM filter on any user attribute of the source identity store to filter the source population. Not applicable on writeback rules and ignored if used. | | `populations.id` (deprecated) | String\[] | Optional | Mutable | Deprecated, use `populationExpression`. If both are present, `populationExpression` applies and `populations.id` ignored. Array of identifiers (UUID) of populations associated with this propagation rule. Not applicable on writeback rules and ignored if used. | | `ruleType` | String | Required | Immutable | Type of this propagation rule. Can be any type from *Propagation store type* of [Propagation store data models by store type](propagation-stores.html#propagation-store-data-models-by-store-type) type. | | `sourceStore.displayName` | String | Required | Immutable | Name displayed in the admin console for the source identity store associated with this propagation rule. | | `sourceStore.id` | String | Required | Immutable | Identifier (UUID) of the source identity store associated with this propagation rule. | | `sourceStore.provisionerId` | String | Required | Immutable | Identifier of the source store provisioner. | | `syncStatus.failedCount` | Integer | N/A | Read-only | Count of failed synchronization events since the last revision. | | `syncStatus.failedDeprovisionCount` | Integer | N/A | Read-only | Count of failed deprovisioning synchronization events since the last revision. | | `syncStatus.groupFailedCount` | Integer | N/A | Read-only | Count of failed group synchronization events since the last revision. | | `syncStatus.groupSuccessCount` | Integer | N/A | Read-only | Count of successful group synchronization events since the last revision. | | `syncStatus.groupTotal` | Integer | N/A | Read-only | Count of groups that will synchronize to the target store. | | `syncStatus.lastResyncAt` | DateTime | N/A | Read-only | Last rule resynchronization in `yyyy-MM-dd'T'HH:mm:ss.SSS'Z'` format. | | `syncStatus.partialSyncTotal` | Integer | N/A | Read-only | Count of users for which an account exists at the target but is out of sync with the source because `onUpdate` is set to `false`. | | `syncStatus.sourceDetails` | String | N/A | Read-only | Details of any source synchronization errors. | | `syncStatus.sourceLastSyncAt` | DateTime | N/A | Read-only | Last source synchronization in `yyyy-MM-dd'T'HH:mm:ss.SSS'Z'` format. | | `syncStatus.sourceSyncState` | String | N/A | Read-only | Current state of synchronization with a source store. Can be `FAILED`, `POLLING`, or `POLL_COMPLETE`. | | `syncStatus.successCount` | Integer | N/A | Read-only | Count of successful synchronization events since the last revision. | | `syncStatus.targetDetails` | String | N/A | Read-only | Details of any target synchronization errors. | | `syncStatus.targetLastSyncAt` | DateTime | N/A | Read-only | Last target synchronization in `yyyy-MM-dd'T'HH:mm:ss.SSS'Z'` format. | | `syncStatus.targetSyncState` | String | N/A | Read-only | Current state of synchronization with a target store. Can be `SYNCING`, `SYNC_COMPLETE`, or `FAILED`. | | `syncStatus.unsyncTotal` | Integer | N/A | Read-only | Count of users for which an account exists at the target but was not synced with the source because `onCreate` is set to `false`. | | `syncStatus.userTotal` | Integer | N/A | Read-only | Count of users that will synchronize to the target store based on the propagation rule's filter. | | `targetStore.displayName` | String | Required | Immutable | Name displayed in the admin console for the target identity store associated with this propagation rule. | | `targetStore.id` | String | Required | Immutable | Identifier (UUID) of the target identity store associated with this propagation rule. | | `targetStore.provisionerId` | String | Required | Immutable | Identifier of the target store provisioner. | | `updatedAt` | DateTime | N/A | Read-only | Date and time the propagation rule was updated. Can be null. | Synchronization states are: * FAILED - An error occurred polling users from the source or pushing users to the target. * POLL\_COMPLETE - Polling has completed on the source. * POLLING - Store is polling for users' information from the source to be potentially synchronized. * SYNC\_COMPLETE - Synchronization has completed on the target. * SYNCING - Synchronizing users to the target is successful. ### Outbound LDAP configuration data object This outbound LDAP `configuration` object is required for outbound LDAP Gateway stores (type `LdapGateway`). An [Inbound LDAP configuration data object](#inbound-ldap-configuration-data-object) is required for inbound LDAP Gateway stores (where users user are provisioned into PingOne). For all other cases, optional and ignored if used. | Property | Type | Required? | Mutable? | Description | | --------------- | ------ | --------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `BASE_DN` | String | Required | Mutable | The location in the LDAP directory structure where users will be created. | | `RDN_ATTRIBUTE` | String | Required | Mutable | Relative distinguished name is the portion of the DN (distinguished name) that uniquely identifies the user in the LDAP directory. Must be `cn` for Microsoft Active Directory, `uid` for PingDirectory. | ### Inbound LDAP configuration data object This inbound LDAP `configuration` object is required for inbound LDAP Gateway stores (where users are provisioned into PingOne). An [Outbound LDAP configuration data object](#outbound-ldap-configuration-data-object) is required for outbound LDAP Gateway stores (type `LdapGateway`). For all other cases, optional and ignored if used. If `AUTHENTICATE_VIA_AD_LDAP` is `false`, then the `GATEWAY_USER_TYPE_*` configuration attributes are optional and ignored if used. Note that `USERS_BASE_DN` is always required and unaffected by the value of `AUTHENTICATE_VIA_AD_LDAP`. `AUTHENTICATE_VIA_AD_LDAP` can only be `true` if a `userTypes` object is configured in the gateway as returned by [Read One Gateway](../gateway-management/gateways/read-one-gateway.html). The remaining `configuration` attributes are required and must exactly match the corresponding attribute in the `userTypes` array object. | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------- | | | **Note:** The `userTypes` object must not have a `newUserLookup` property if it is to be used with `AUTHENTICATE_VIA_AD_LDAP` as `true`. | For example, the object in the `userTypes` array is: ```json "userTypes": [ { "id": "522eea26-d268-4494-a826-434a6b24f35d", "name": "AD user type", "passwordAuthority": "LDAP", "searchBaseDn": "OU=inbound,OU=test,OU=LdapGatewayTest,DC=ldap-test1,DC=lab", "orderedCorrelationAttributes": [ "dn" ], "allowPasswordChanges": false } ], ``` The mapping is: * `allowPasswordChanges` maps to `GATEWAY_USER_TYPE_ALLOW_PASSWORD_CHANGES` * `id` maps to `GATEWAY_USER_TYPE_ID` * `name` maps to `GATEWAY_USER_TYPE_NAME` * `orderedCorrelationAttributes` maps to `GATEWAY_USER_TYPE_CORRELATION_ATTRIBUTES` where, for multiple attributes, the JSON array of strings is converted to a single comma-separated string. * `passwordAuthority` maps to `GATEWAY_USER_TYPE_PASSWORD_AUTHORITY` | Property | Type | Required? | Mutable? | Description | | ------------------------------------------ | ------- | ----------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `AUTHENTICATE_VIA_AD_LDAP` | Boolean | Required | Mutable | Whether users are authenticated using LDAP. | | `GATEWAY_USER_TYPE_ALLOW_PASSWORD_CHANGES` | Boolean | Required/Optional | Mutable | Whether users are permitted to change their password. Required as described in this section, optional for all other rules and ignored if used. | | `GATEWAY_USER_TYPE_CORRELATION_ATTRIBUTES` | String | Required/Optional | Mutable | A comma-separated string of one or more attributes. Required as described in this section, optional for all other rules and ignored if used. | | `GATEWAY_USER_TYPE_ID` | String | Required/Optional | Mutable | Identifier (UUID) of the user type to which this configuration applies. Required as described in this section, optional for all other rules and ignored if used. | | `GATEWAY_USER_TYPE_NAME` | String | Required/Optional | Mutable | Name of the user type to which this configuration applies. Required as described in this section, optional for all other rules and ignored if used. | | `GATEWAY_USER_TYPE_PASSWORD_AUTHORITY` | String | Required/Optional | Mutable | Password authority associated with the user type. Required as described in this section, optional for all other rules and ignored if used. | | `MFA_USER_DEVICE_MANAGEMENT` | String | Optional | Mutable | How incoming user devices are managed. Can be `Merge with devices in PingOne`, `Overwrite devices in PingOne`, or `Do not manage devices`. For more information, see [Provisioning options reference](https://docs.pingidentity.com/integrations/pingone/pingone_integration_kit/pf_p1_ik_provisioning_options_reference.html). | | `USERS_BASE_DN` | String | Required | Mutable | The LDAP directory location from where the users will be synced into PingOne. | ## Propagation synchronized rule data model | Property | Type | Required? | Mutable? | Description | | ------------------------------ | --------- | --------- | --------- | ---------------------------------------------------------------------------------------------- | | `details` | String | N/A | Read-only | Details of any rule synchronization errors. | | `environment.id` | String | N/A | Read-only | Identifier (UUID) of the PingOne environment associated with the propagation rule. | | `lastSyncAt` | DateTime | N/A | Read-only | Last rule synchronization in `yyyy-MM-dd'T'HH:mm:ss.SSS'Z'` format. | | `rule.active` | Boolean | N/A | Read-only | Whether the rule is active or not. | | `rule.id` | String | N/A | Read-only | Identifier (UUID) of the synchronized rule. | | `rule.name` | String | N/A | Read-only | Name of the synchronized rule. | | `sourceStore.id` | String | N/A | Read-only | Identifier (UUID) of the source identity store associated with this propagation rule. | | `sourceStore.name` | String | N/A | Read-only | Name of the source identity store associated with this propagation rule. | | `sourceStore.type` | String | N/A | Read-only | Type of the source identity store associated with this propagation rule. | | `status` | String | N/A | Read-only | Status of the rule synchronization. Can be `SUCCESS` or `FAILED`. | | `syncedMemberships` | Object\[] | N/A | Read-only | Array of objects describing the group memberships of the rule and its status within the group. | | `syncedMemberships.details` | String | N/A | Read-only | Details of any rule group synchronization errors. | | `syncedMemberships.group.id` | String | N/A | Read-only | Identifier (UUID) of the group of which the rule is a member. | | `syncedMemberships.lastSyncAt` | DateTime | N/A | Read-only | Last rule group synchronization in `yyyy-MM-dd'T'HH:mm:ss.SSS'Z'` format. | | `syncedMemberships.status` | String | N/A | Read-only | Status of the rule group synchronization. Can be `SUCCESS` or `FAILED`. | | `targetStore.id` | String | N/A | Read-only | Identifier (UUID) of the target identity store associated with this propagation rule. | | `targetStore.name` | String | N/A | Read-only | Name of the target identity store associated with this propagation rule. | | `targetStore.type` | String | N/A | Read-only | Type of the target identity store associated with this propagation rule. | | `type` | String | N/A | Read-only | Status of the rule synchronization. Can be `INBOUND` or `OUTBOUND`. | ## Additional rule data models by request [Read All Rules](propagation-rules/read-all-rules.html) and [Read One Plan's Rules](propagation-rules/read-one-plans-rules.html) return a [Propagation rule data model](#propagation-rule-data-model) modified as described in the table. | Property | Type | Required? | Mutable? | Description | | ----------------- | --------- | --------- | --------- | ----------------------------------------------------------------------------------------------- | | `rules` | Object\[] | N/A | Read-only | Array of rule objects as defined in [Propagation rule data model](#propagation-rule-data-model) | | `rules.rule` | Object | N/A | Read-only | Rule object, replaces `id` in [Propagation rule data model](#propagation-rule-data-model) | | `rules.rule.id` | String | N/A | Read-only | Unique identifier (UUID) of the propagation rule | | `rules.rule.name` | String | N/A | Read-only | Name of the propagation rule | The requests [Read All Synced Rules for a User](propagation-rules/read-all-synced-rules.html), [Read One Synced Rule for a User](propagation-rules/read-one-synced-rule.html), [Read All Synced Rules for a Group](propagation-rules/read-all-synced-rules-for-a-group.html), and [Read One Synced Rule for a Group](propagation-rules/read-one-synced-rule-for-a-group.html) return a [Propagation rule data model](#propagation-rule-data-model) modified as described in the table. | Property | Type | Required? | Mutable? | Description | | ------------------------- | --------- | --------- | --------- | ------------------------------------------------------------------------------------------------------------ | | `syncedRules` | Object\[] | N/A | Read-only | Array of synchronized rule objects as defined in \[Propagation rule data model]#propagation-rule-data-model) | | `syncedRules.rule` | Object | N/A | Read-only | Rule object, replaces `id` in [Propagation rule data model](#propagation-rule-data-model) | | `syncedRules.rule.active` | Boolean | N/A | Read-only | Whether the rule is active or not | | `syncedRules.rule.id` | String | N/A | Read-only | Unique identifier (UUID) of the propagation rule | | `syncedRules.rule.name` | String | N/A | Read-only | Name of the propagation rule | The requests [Read All Synced Groups for a Rule](propagation-rules/read-all-synced-groups-for-a-rule.html) and [Read One Synced Group for a Rule](propagation-rules/read-one-synced-group-for-a-rule.html) return a [Groups data model](../groups.html#groups-data-model) modified as described in the table. | Property | Type | Required? | Mutable? | Description | | ----------------------- | --------- | --------- | --------- | ------------------------------------------------------------------------------------------------------- | | `syncedGroups` | Object\[] | N/A | Read-only | Array of synchronized group objects as defined in [Groups data model](../groups.html#groups-data-model) | | `syncedGroups.group` | Object | N/A | Read-only | Group object, replaces `id` in [Groups data model](../groups.html#groups-data-model) | | `syncedGroups.group.id` | String | N/A | Read-only | Unique identifier (UUID) of the group | ## 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. |