cancel
Showing results for 
Show  only  | Search instead for 
Did you mean: 

How to edit the source create account profile via REST API

How to edit the source create account profile via REST API

When provisioning a new account to a source, IdentityNow utilizes the configurations in the Create Account Profile on the source to determine the values of the new source account attributes.  Most source connectors enabled for provisioning have a default Create Account Profile. Some customizations to the Create Account 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 Create Account 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 Create Account Profile.  At this point it is helpful to view the Create Account Profile in the IdentityNow UI to see how the JSON corresponds.  Go to Connections > Sources > (Source) > Accounts > Create Account 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 Create Account 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 Create Account 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 Create Account 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 Create Account 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 Create Account Profile JSON as the request body.  After receiving a successful 200 response code, you can view the Create Account 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 Create Account 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?

How to update the "isRequired" attribute to true? It doesn't work through the API (web service connector).

@veroniqueb 

The "isRequired" attribute is not updatable.  It is the external source itself that controls whether or not an attribute is required to create an account.

Hi @cr

I'm assuming 'Create Unique Account ID' is a cloud rule where some validation is done to evaluate the value of uniqueCounter?

Version history
Revision #:
24 of 24
Last update:
‎Mar 28, 2023 02:57 PM
Updated by: