--- title: Synchronize changes to a PingOne environment description: This section describes the configuration that is necessary to synchronize changes to a PingOne environment. PingDataSync supports synchronization of single and multivalued attributes to PingOne. To view an example configuration, see the file located at /config/sample-dsconfig-batch-files/reference-ping-one-sync-destination-configuration.dsconfig. component: pingdirectory version: 11.0 page_id: pingdirectory:pingdatasync_server_administration_guide:pd_sync_changes_p1_env canonical_url: https://docs.pingidentity.com/pingdirectory/11.0/pingdatasync_server_administration_guide/pd_sync_changes_p1_env.html revdate: September 13, 2023 page_aliases: ["pd_sync_create_p1_sync_dest.adoc", "pd_sync_config_json_attr_mapping.adoc", "pd_sync_config_constructed_attr_mapping.adoc", "pd_sync_correlate_entries.adoc", "pd_sync_consids_lims.adoc"] section_ids: creating-a-pingone-sync-destination: Creating a PingOne sync destination config_json_attr_map: Configuring JSON attribute mappings about-this-task: About this task steps: Steps example: Example: example-2: Example: example-3: Example: configuring-constructed-attribute-mappings: Configuring constructed attribute mappings correlating-entries: Correlating entries considerations-and-limitations: Considerations and limitations renaming-entries-isnt-allowed: Renaming entries isn't allowed populations: Populations multivalued-attributes: Multivalued attributes --- # Synchronize changes to a PingOne environment This section describes the configuration that is necessary to synchronize changes to a PingOne environment. PingDataSync supports synchronization of single and multivalued attributes to PingOne. To view an example configuration, see the file located at `/config/sample-dsconfig-batch-files/reference-ping-one-sync-destination-configuration.dsconfig`. | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | When configuring a sync pipe in PingDataSync to synchronize users to a PingOne destination, you must include a constructed attribute mapping *(tooltip: \
\

Matching corresponding attributes between an IdP and an SP to identify federated users or add supplemental user information.\

\
)* named `resourceType` with a value-pattern of `user`. | ## Creating a PingOne sync destination Before you create a PingOne sync destination, make sure you have the following information ready: * Environment ID (*environment-id*) * OAuth client ID (*oauth-client-id*) * OAuth client secret (*oauth-client-secret*) Learn more about obtaining these values in [Creating a PingOne worker application](pd_sync_prerequisites.html#pds_create_p1_worker). The following sample creates a PingOne sync destination. ``` dsconfig create-sync-destination \ --destination-name PingOne \ --type ping-one-customer \ --set api-url:https://api.pingone.com/v1 \ --set auth-url:https://auth.pingone.com/[PING_ONE_ENV_ID]/as/token \ --set environment-id:[PING_ONE_ENV_ID] \ --set oauth-client-id:[PING_ONE_OAUTH_CLIENT_ID] \ --set oauth-client-secret:[PING_ONE_OAUTH_CLIENT_SECRET] ``` ## Configuring JSON attribute mappings Add the JSON attribute mapping type with sub-objects (the JSON attribute mapping field) that allow you to map individual fields. ### About this task If a source attribute doesn't have a value, the corresponding field is omitted. | | | | - | ----------------------------------------------------------------------- | | | Use JSON attribute mappings rather than constructed attribute mappings. | ### Steps 1. To create an attribute map, run `dsconfig` with the `create-attribute-map` option. #### Example: The following example creates an attribute map titled `PingDirectory_to_PingOne_User_Map`. ``` dsconfig create-attribute-map \ --map-name PingDirectory_to_PingOne_User_Map ``` 2. To create the attribute mapping, run `dsconfig` with the `create-attribute-mapping` option. #### Example: The following example creates the attribute mapping to `PingDirectory_to_PingOne_User_Map`. ``` dsconfig create-attribute-mapping \ --map-name PingDirectory_to_PingOne_User_Map \ --mapping-name name \ --type json ``` 3. To map JSON attributes, run `dsconfig` with the `create-json-attribute-mapping-field` option. #### Example: The following example creates the JSON attribute mapping field `formatted` from the `cn` attribute. ``` dsconfig create-json-attribute-mapping-field \ --map-name PingDirectory_to_PingOne_User_Map \ --mapping-name name \ --field-name formatted \ --set from-attribute:cn \ --set json-type:string ``` The following example creates the JSON attribute mapping field `given` from the `givenName` attribute. ``` dsconfig create-json-attribute-mapping-field \ --map-name PingDirectory_to_PingOne_User_Map \ --mapping-name name \ --field-name given \ --set from-attribute:givenName \ --set json-type:string ``` The following example creates the JSON attribute mapping field `family` from the `sn` attribute. ``` dsconfig create-json-attribute-mapping-field \ --map-name PingDirectory_to_PingOne_User_Map \ --mapping-name name \ --field-name family \ --set from-attribute:sn \ --set json-type:string ``` ## Configuring constructed attribute mappings | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | You should use JSON attribute mappings instead of constructed attribute mappings. Learn more in [Configuring JSON attribute mappings](#config_json_attr_map). | The PingOne User model contains simple JSON attributes like `"title": "Director"` as well as complex JSON objects like `\{"name": \{"given": "Jane", "family": "Doe"}}`. To ensure accurate processing when you construct attribute mappings that interact with complex objects, construct valid JSON strings and use the command `jsonEscape`, as the following example shows. ``` dsconfig create-attribute-mapping \ --map-name PingDirectory_to_PingOne_User_Map \ --mapping-name name \ --type constructed \ --set 'value-pattern:{{"given":"{givenname:jsonEscape}","family":"{sn:jsonEscape}"}}' ``` Some attributes in the User resource are operational and cannot be modified by synchronizing data. Learn more in the [PingOne Platform API Reference](https://developer.pingidentity.com/pingone-api/introduction.html). ## Correlating entries The PingOne User Resource model provides an attribute named `externalId`. To ensure that users correlate to the appropriate entry in PingDirectory, map `entryUUID` to this value and configure `externalId` as a destination-correlation-attribute on the Sync class. ## Considerations and limitations There are limitations and other constraints to consider when synchronizing changes to a PingOne environment. ### Renaming entries isn't allowed As a sync destination, PingOne doesn't allow `moddn` operations to rename an entry. When creating a sync class, set the `allow-destination-renames` option to `false` to prevent PingDataSync from attempting to rename entries and then logging related errors. For example: ``` dsconfig create-sync-class \ --pipe-name PingDirectory_to_PingOne \ --class-name "PingDirectory_to_PingOne User Sync Class" \ --set allow-destination-renames:false \ --set attribute-map:PingDirectory_to_PingOne_User_Map \ --set auto-mapped-source-attribute:-none- \ --set destination-correlation-attributes:externalId \ --set destination-correlation-attributes:username \ --set destination-correlation-attributes:email \ --set destination-create-only-attribute:resourceType \ --set creates-as-modifies:true \ --set include-filter:(objectClass=person) ``` | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | You can find the previous example in the PingDataSync distribution. Learn more in the following file: `config/sample-dsconfig-batch-files/reference-pingone-sync-destination-configuration.dsconfig`. | ### Populations | | | | - | ---------------------------------------------------------- | | | All PingOne user resources must exist within a population. | The PingOne synchronization destination provides the following methods for managing a user's population: * If a single population is in use, set the configuration attribute `default-population-id` on the sync destination. * If multiple populations are in use, use a constructed attribute mapping *(tooltip: \
\

Matching corresponding attributes between an IdP and an SP to identify federated users or add supplemental user information.\

\
)*. The following syntax provides an example with a constructed attribute mapping: ``` dsconfig create-attribute-mapping \ --map-name PingDirectory_to_PingOne_User_Map \ --mapping-name population \ --type constructed \ --set 'value-pattern:{{"id":"[DEFAULT_POPULATION_ID]"}}' ``` To set the population, construct a valid JSON object. ### Multivalued attributes If your incoming data is in JSON format, configure your PingOne multivalued attribute as JSON and use a JSON attribute mapping. If your incoming data is not in JSON format, you can configure your PingOne multivalued attribute as JSON and use a constructed attribute mapping. Otherwise, you must configure your PingOne multivalued attribute as `DECLARED` and use a direct attribute mapping. | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | | Direct attribute mapping does not work with JSON multivalued PingOne attributes even with an attribute with the same name and value in PingDirectory. |