How to Edit the Source Account Create Profile via REST API

How to Edit the Source Account Create Profile via REST API

When provisioning a new account to a source, IdentityNow utilizes the configurations in the Account Create Profile on the source to determine the values of the new source account attributes.  Most source connectors enabled for provisioning have a default Account Create Profile. Some customizations to the Account Create Profile can be done in the user interface, but others must be done through the REST API.  In this article, we will walk through some configurations that can only be done via the REST API such as adding additional attributes, applying inline transform logic, and applying an existing transform.

The first step is to retrieve the Account Create Profile from the specific source you want to modify.  This is done via the REST API endpoint GET /v3/sources/{sourceId}/provisioning-policies. You can use an API client like Postman or cURL for all the API calls utilized in this process.  The JSON response body will contain all provisioning policies for this source: CREATE, CREATE_GROUP, UPDATE_GROUP.  But we are only concerned with the CREATE provisioning policy for our purposes, and we can retrieve just that policy by specifying the usageType as a query parameter to our REST API call: GET /v3/sources/{sourceId}/provisioning-policies/CREATE. Here is an example JSON response body of a source's CREATE provisioning policy:

    {
        "name": "account",
        "description": null,
        "usageType": "CREATE",
        "fields": [
            {
                "name": "dn",
                "transform": {
                    "type": "rule",
                    "attributes": {
                        "name": "Create Unique Account ID"
                    }
                },
                "attributes": {
                    "template": "uid=$(firstname).$(lastname)$(uniqueCounter),ou=users,dc=example,dc=com",
                    "cloudMaxUniqueChecks": "50"
                },
                "isRequired": true,
                "type": "string",
                "isMultiValued": false
            },
            {
                "name": "password",
                "transform": {
                    "type": "rule",
                    "attributes": {
                        "name": "Create Password"
                    }
                },
                "attributes": {},
                "isRequired": true,
                "type": "secret",
                "isMultiValued": false
            },
            {
                "name": "cn",
                "transform": {
                    "type": "identityAttribute",
                    "attributes": {
                        "name": "displayName"
                    }
                },
                "attributes": {},
                "isRequired": true,
                "type": "string",
                "isMultiValued": false
            },
            {
                "name": "givenName",
                "transform": {
                    "type": "identityAttribute",
                    "attributes": {
                        "name": "firstname"
                    }
                },
                "attributes": {},
                "isRequired": false,
                "type": "string",
                "isMultiValued": false
            },
            {
                "name": "sn",
                "transform": {
                    "type": "identityAttribute",
                    "attributes": {
                        "name": "lastname"
                    }
                },
                "attributes": {},
                "isRequired": true,
                "type": "string",
                "isMultiValued": false
            },
            {
                "name": "mail",
                "transform": {
                    "type": "rule",
                    "attributes": {
                        "name": "Create Unique LDAP Attribute"
                    }
                },
                "attributes": {
                    "template": "$(firstname).$(lastname)$(uniqueCounter)@YOURDOMAIN.COM",
                    "cloudMaxUniqueChecks": "50"
                },
                "isRequired": false,
                "type": "string",
                "isMultiValued": false
            },
            {
                "name": "uid",
                "transform": {
                    "type": "rule",
                    "attributes": {
                        "name": "Create Unique LDAP Attribute"
                    }
                },
                "attributes": {
                    "template": "$(firstname).$(lastname)$(uniqueCounter)",
                    "cloudMaxUniqueChecks": "50"
                },
                "isRequired": false,
                "type": "string",
                "isMultiValued": false
            }
        ]
    }

Each item in the fields array corresponds to an attribute on the Account Create Profile.  At this point it is helpful to view the Account Create Profile in the IdentityNow UI to see how the JSON corresponds.  Go to Connections > Sources > (Source) > Accounts > Create Profile and compare each attribute in the UI to its corresponding definition in the JSON.  If you want to add an additional attribute, you can copy the JSON of an existing attribute and modify it accordingly.  You can only add attributes to the Account Create Profile that are part of the Source Account Schema.  Change the name attribute in the the JSON to exactly match the attribute name in the Source Account Schema and configure the new attribute to your specifications. 

Under the transform attribute is where the logic that generates the value of this attribute in a new source account is defined.  Notice the different values in the type under this section.  When the value of the type attribute is "identityAttribute" its value is taken directly from the specified Identity Attribute.  If the value is "rule" then the specified generator is generating the value.  The value could also be "static" if the same specified string value will be used for all accounts created with this Account Create Profile.

Inline transform logic to generate the attribute value can be applied by adding the transform primitive operation definitions directly to the attribute on the Account Create Profile under the transform section as you can see in this example:

    {
            "name": "mobile",
            "transform": {
                "attributes": {
                    "values": [
                        {
                            "attributes": {
                                "input": {
                                    "attributes": {
                                        "attributeName": "secondaryPhoneNumber",
                                        "sourceName": "Employees"
                                    },
                                    "type": "accountAttribute"
                                }
                            },
                            "type": "e164phone"
                        },
                        {
                            "attributes": {
                                "value": "no mobile phone"
                            },
                            "type": "static"
                        }
                    ]
                },
                "type": "firstValid"
            },
            "attributes": {},
            "isRequired": false,
            "type": "string",
            "isMultiValued": false
        }

Alternatively, you can apply an existing transform here:

{
            "name": "telephoneNumber",
            "transform": {
                "attributes": {
                    "id": "FormatWorkPhone"
                },
                "type": "reference"
            },
            "attributes": {},
            "isRequired": false,
            "type": "string",
            "isMultiValued": false
        }

In the example above we have applied the existing "FormatWorkPhone" transform by changing the value of the type attribute to "reference" and the value of the id attribute to the name of the transform that is defined below:

{
        "id": "386a9782-9882-492a-8735-5328fffd8351",
        "name": "FormatWorkPhone",
        "type": "firstValid",
        "attributes": {
            "values": [
                {
                    "attributes": {
                        "input": {
                            "attributes": {
                                "attributeName": "phoneNumber",
                                "sourceName": "Employees"
                            },
                            "type": "accountAttribute"
                        }
                    },
                    "type": "e164phone"
                },
                {
                    "attributes": {
                        "value": "none"
                    },
                    "type": "static"
                }
            ]
        },
        "internal": false
    }

Note: Transforms created via the v1 REST API endpoint, POST /cc/api/transform/create, only have an id attribute, which is the human friendly name, whereas transforms created via the v3 REST API endpoint, POST /v3/transforms, have an id attribute that is a GUID and a name attribute that is the human friendly name.  If the existing transform you want to reference was created via the v1 REST API endpoint, use the id value.  If the existing transform you want to reference was created via the v3 REST API endpoint, use the name value.

Once you have made the required changes to your Account Create Profile JSON, you will need to upload those changes to the tenant via the PUT /v3/sources/{sourceId}/provisioning-policies/CREATE API endpoint using your modified Account Create Profile JSON as the request body.  After receiving a successful 200 response code, you can view the Account Create Profile in the IdentityNow UI to see your changes.  If you have applied inline transform logic or referenced an existing transform on an attribute, no radio button will be selected, but instead "Custom Transform" will be the value displayed in the "Transform" text box for that attribute as you can see in the screenshot below:

ACP telephoneNumber.png

Now you are ready to test your changes by triggering provisioning to the source.  If the values for your attributes are not getting generated correctly, make adjustments to the Account Create Profile JSON, update via the REST API, and retest.

Labels (2)
Comments

It is crazy that userPrincipleName is not in the default create profile.  Any chance this is going to be added in the near future?

Version history
Revision #:
21 of 21
Last update:
‎Sep 09, 2021 02:24 PM
Updated by:
 
Contributors