Importing User Data
URL:#
POST https://{{client}}.api.451.io/v2/users/importHeaders:#
- Authentication = Bearer: {{api_key}}
- Feature = {{feature}}
Body Schema:#
The body schema of the payload consists of two main elements…the structure (template) and the data (items array).
Template Parameter
In general, there are two ways you can build a schema for importing data into Element (full examples are at the bottom of this document):
- Pre-defined/Element template (using a GUID)
{ "item": { "template": "", "items": [{...},{...}], "options":{} } }- The template can be passed inline in the request body itself as an object/array (what is shown below) or if there's an existing template in the system a guid can be passed a string (what is shown above).
- Inline template
{ "template": [ "columns": [ "field":"", "mode":"", "slug":"", "formula":"", "transformations":[], "scope":[], "validations":[], "type":"string", "range":[] "empty":"" ] ], "items": { [{...},{...}], }, "options":{} }- When building an inline template, the properties are as follows:
- "columns" : [array] - (required) list of object properties to be exported for each row.
- "field" : "string" - (required) Friendly name of the field to be imported. Does not have to match the system friendly name.
- "mode" : "string" - (required) Generally should be set to “slug”. Other options include “skip” and “calculated”.
- “slug” - This imports the values from the matching item to the slug.
- “skip” - This skips importing the data for that specific slug. The field name and slug name (can be any text string) still need to be populated in the template and the slug name needs to be present in the data.
- “calculated” - The formula value needs to be included in the template and the slug in the data import, though the value of the item is ignored, so it is best to just leave it blank.
- "slug" : "string" - (required) Slug of the referenced mapping. When using “mode”: “skip” this can be any text string and does not have to be a real slug.
- “formula” : “string” - (optional) A formula to be applied while importing using calculated mode (see Calculated Fields).
- "transformations" : [array] - (optional) Any transformation to be applied on the value.
- “scope” : “string” - (sometimes required) Used for importing multiple values for the type of fields (for example test scores or milestones).
- "validations" : [array] - (optional) Any validation to be applied to the value.
- “type” : “string” - (optional) The type of data to be imported. (”string” or for example)
- “range” : [array] - (optional) Example would be ["unique"] for fields you want to match on.
- "empty" : "mixed" - (optional) Action to do when the value is empty.
- “remove” - Remove the blank value from the data and don’t import it.
- null - Import the blank value.
- “null” - Fill with null
- “emptystring” - Fill with an empty string.
- “now” - Fill with the current date and time.
- "columns" : [array] - (required) list of object properties to be exported for each row.
- When building an inline template, the properties are as follows:
“Items” Parameter
The “items” array is the actual data being imported can be constructed in two ways:
- Named Keys
{ "item": { ... "items": [ "[friendly-field-name-1]":"", "[friendly-field-name-2]":"", ... ], ... } }- In this design, it can either use the “slug” name of each field OR (if you configure the “options” parameter to be “keyBy”:”field”) it uses the “field” parameter from the “template” (previous section) to have the key be the “friendly name” you assigned to that property (while the value to the right of the colon is the actual value you want to import)
- Number Keys
{ "item": { ... "items": [ "0":"", "1":"", ... ], ... } }- In this design, its simply follows the order of the parameters from the “template” (previous section). The value to the righty of the colon is the actual value you want to import.
If using calculated fields, you can use either numbers as the object key, which starts at 0, or use the slug/“field” name. (Key 0 is equal to column 1 in the layout). Either way, the value for the calculate column would be empty as the data is populated by the formula.
“Options” Parameter
The “options” parameter consists of an object that can help define how the import will work. Kevy:Values to pass in the object are:
- “action” : “string” - (optional) Can be set to update, upsert, or insert. The default is upsert.
- “dry” : boolean - (optional) Can be true or false. True will run the import without writing to the database, the same way a test flat file import would act.
- “keyBy”: “string” - (optional) Can be set to “field” and match on the field names instead of the slug names or numeric value. This will allow you to import multiple values for the same slug that have different scopes at the same time. (i.e. applications, milestones, etc)
Example 1 - Using Saved Template and Named Keys (slugs)
Request:
POST https://{{client}}.{{api}}/v2/users/import
URL parameters:
{{client}}: Assigned client subdomain.
{{api}}: URL of the Element451 API. "api.451.io" for Production API.
Request headers:
Feature: Feature token for that client
Authorization: Bearer API Key
Content-Type: 'application/json'
Request body parameters:
{
"item": {
"template": "element.template.451",
"items": [
{
"user-email-address": "john.smith@example.com",
"user-first-name": "John",
"user-last-name": "Smith"
},
{
"user-last-name": "Jenkins",
"user-email-address": "jane.jenkins@example.com",
"user-first-name": "Jane"
}
]
}
}
Expected Response:
Status 201
{
"data": {
"stats": {
"created": 0,
"updated": 2
},
"error": null,
"warnings": [],
"result": {
"updated": [
"621561e2f7fa620d22575e33",
"621561e6f7fa620d22575e35"
]
}
}
}Example 2 - Using Saved Template, Number Keys and Calculated Fields
Request:
POST https://{{client}}.{{api}}/v2/users/import
URL parameters:
{{client}}: Assigned client subdomain.
{{api}}: URL of the Element451 API. "api.451.io" for Production API.
Request headers:
Feature: Feature token for that client
Content-Type: 'application/json'
Request body parameters:
Note: Key 3 (column 4) is not being imported and key 4 (column 5) is the calculated column that uses key 3 (column 4) in the calculation.
{
"item": {
"template": "client.template.1139",
"items": [
{
"0":"John",
"1": "john.smith@example.com",
"2": "Smith",
"3":"Y",
"4":""
}
]
}
}
Expected Response:
Status 201
{
"data": {
"stats": {
"created": 0,
"updated":
},
"error": null,
"warnings": [],
"result": {
"updated": [
"621561e2f7fa620d22575e33"
]
}
}
}
Example 3 - Using Inline Template and Number Keys
Request:
POST https://{{client}}.{{api}}/v2/users/import
URL parameters:
{{client}}: Assigned client subdomain.
{{api}}: URL of the Element451 API. "api.451.io" for Production API.
Request headers:
Feature: Feature token for that client
Content-Type: 'application/json'
Request body parameters:
{
"item": {
"template": {
"columns": [
{
"field": "Email",
"mode": "slug",
"slug": "user-email-address",
"formula": "",
"transformations": [],
"scope": [],
"validations": [],
"type": "string",
"range": [
"unique"
],
"empty": "remove"
},
{
"field": "First Name",
"mode": "slug",
"slug": "user-first-name",
"formula": "",
"transformations": [],
"scope": [],
"validations": [],
"type": "string",
"range": [],
"empty": "remove"
},
{
"field": "Last Name",
"mode": "slug",
"slug": "user-last-name",
"formula": "",
"transformations": [],
"scope": [],
"validations": [],
"type": "string",
"range": [],
"empty": "remove"
}
]
},
"items": [
{
"0": "john.smith@example.com",
"1": "John",
"2": "Smith"
},
{
"0": "jane.jenkins@example.com",
"1": "Jane",
"2": "Jenkins"
}
]
}
}
Expected Response:
Status 201
{
"data": {
"stats": {
"created": 0,
"updated": 2
},
"error": null,
"warnings": [],
"result": {
"updated": [
"621561e2f7fa620d22575e33",
"621561e6f7fa620d22575e35"
]
}
}
}
Example 4 - Using Inline Template and Named Keys (keyBy:”field”)
Request:
POST https://{{client}}.{{api}}/v2/users/import
URL parameters:
{{client}}: Assigned client subdomain.
{{api}}: URL of the Element451 API. "api.451.io" for Production API.
Request headers:
Feature: Feature token for that client
Content-Type: 'application/json'
Request body parameters:
{
"item": {
"template": {
"columns": [
{
"field": "ElementID",
"mode": "slug",
"slug": "user-elementid",
"transformations": [],
"scope": [],
"validations": [],
"type": "mongoid",
"range": [
"unique"
]
},
{
"field": "Applicationstatus1",
"mode": "slug",
"slug": "user-applications-status-*",
"transformations": [],
"scope": {
"guid": "client.applications.8239",
"term": "client.terms.1841"
},
"validations": [],
"type": "string",
"empty": "remove"
},
{
"field": "Applicationmajor1",
"mode": "slug",
"slug": "user-applications-major-*",
"transformations": [
{
"params": {
"from": "name",
"enabled": true,
"failOnUnmatch": null,
"to": "guid",
"data_source": "data_source.majors",
"dimensions": {
"name": "Name",
"guid": "Guid",
"code": "Code",
"custom_1": "Custom 1",
"source_major_code": "major code",
"description": "Description"
},
"taxonomy": null,
"root_level": false
},
"type": "formAutomapImport"
}
],
"scope": {
"guid": "client.applications.8239",
"term": "client.terms.1841"
},
"type": "string",
"empty": "remove"
},
{
"field": "Applicationstatus2",
"mode": "slug",
"slug": "user-applications-status-*",
"transformations": [],
"scope": {
"guid": "client.applications.8239",
"term": "client.terms.1841"
},
"validations": [],
"type": "string",
"empty": "remove"
},
{
"field": "Applicationmajor2",
"mode": "slug",
"slug": "user-applications-major-*",
"formula": "",
"transformations": [
{
"params": {
"from": "name",
"enabled": true,
"failOnUnmatch": null,
"to": "guid",
"data_source": "data_source.majors",
"dimensions": {
"name": "Name",
"guid": "Guid",
"code": "Code",
"custom_1": "Custom 1",
"source_major_code": "major code",
"description": "Description"
},
"taxonomy": null,
"root_level": false
},
"type": "formAutomapImport"
}
],
"scope": {
"guid": "client.applications.8239",
"term": "client.terms.1842"
},
"type": "string",
"empty": "remove"
}
]
},
"items": [
{
"ElementID": "650c4e6e5220c2ca63046c6",
"Applicationstatus1": "submitted",
"Applicationmajor1": "Accounting",
"Applicationstatus2": "submitted",
"Applicationmajor2": "Biological Sciences"
}
],
"options": {
"keyBy": "field"
}
}
}
Expected Response:
Status 201
{
"data": {
"stats": {
"created": 0,
"updated": 1
},
"error": null,
"warnings": [],
"result": {
"updated": [
"650c4e6e5220c2ca63046c6"
]
}
}
}
Was this page helpful?