Who is this article for?

Administrators responsible for managing user data synchronisation between external systems and Ideagen Aviation Safety (Cora).

Access to S3 bucket and People module administration is required.

The user sync process allows you to create, update, archive, or reinstate users in Ideagen Aviation Safety (Cora) by uploading a JSON file to a designated S3 bucket.

1. Understanding the user sync process

The user sync process involves creating a JSON file containing user data that will create, update, archive, or reinstate users in the People module. You place the JSON file into an S3 bucket provided by Ideagen, and the system automatically consumes and processes it into your tenant.

Note: During the sync process, access to the People and Groups modules in the Ideagen Aviation Safety (Cora) UI will be disabled to avoid interference. Once complete, these modules will be re-enabled.

2. Understanding field requirements

When creating or updating a user, most fields are mandatory because the user sync will update the user to match the sync file. The following table shows all available fields and their requirements:

*Mandatory

**Mandatory for account to be SSO enabled

Note: If the UserGroup field is provided, it will add or remove users to groups as required. If an empty array is provided ([]), the user will be removed from all but the system groups (All Org Users, System Wide Access). If the attribute is not provided at all, the UserGroups will not be synced and users will remain in their existing groups.

Important: If a user is to be removed from the System Wide Access group, this MUST be done manually to avoid total lockout from the Administration.

3. Updating users

When updating a user, you must provide all existing information that should not change, otherwise it will be cleared or set to a default value. If attributes are omitted altogether, the file will fail validation.

4. Archiving users

When archiving a user, the target user for reassigned tasks must already exist or be created in the same file. If the reassigned user has been created in a previous sync or current sync, you can use the ExternalId of that user.

5. Creating users

If you create a user with the same ExternalId as a previously archived user, that user will be reinstated on Ideagen Aviation Safety (Cora) rather than a new user being created.

6. Creating a JSON file

This section provides examples of how user entries should be formatted in the JSON file. The following table shows the status commands:

6.1 Create (SSO user)

[{ 
"Email": "test.user@ideagen.com",
"status": 0,
"Forename": "Test",
"Surname": "user",
"UserName": "Test.User",
"JobTitle": "I am a Test User",
"OrganisationalUnit": "3a7e9387-3996-469f-b1d1-1edc5e9eba54",
"ExternalId": "test.user@ideagen.com",
"ProviderId": "support",
"TelephoneNumber": "",
"MobileNumber": "",
"Culture": "en-GB",
"Timezone": "UTC", 
"UserGroups": ["Group 1", "Group 2", "Group 3"],
"EnableLogin": true,
"Isexternallymanaged": true
}]

Note: Remove "Isexternallymanaged" for non-SSO users.

6.2 Update (SSO user)

[{ 
"Email": "test.user@ideagen.com",
"status": 1,
"Forename": "Test",
"Surname": "user",
"UserName": "Test.User",
"JobTitle": "I am a Test User",
"OrganisationalUnit": "3a7e9387-3996-469f-b1d1-1edc5e9eba54",
"ExternalId": "test.user@ideagenplc.com",
"ProviderId": "support",
"TelephoneNumber": "",
"MobileNumber": "",
"Culture": "en-GB",
"Timezone": "UTC", 
"UserGroups": ["Group 1", "Group 2", "Group 3"],
"EnableLogin": true,
"Isexternallymanaged": true
}]

Note: Remove "Isexternallymanaged" for non-SSO users.

6.3 Archive

[{ 
"status": 2,
"ExternalId": "test.user@ideagen.com",
"ReasignedUserId": "test2.user@ideagen.com",
}]

6.4 Reinstate (SSO user)

[{ 
"Email": "test.user@ideagen.com",
"status": 3,
"Forename": "Test",
"Surname": "user",
"UserName": "Test.User",
"JobTitle": "I am a Test User",
"OrganisationalUnit": "3a7e9387-3996-469f-b1d1-1edc5e9eba54",
"ExternalId": "test.user@ideagen.com",
"ProviderId": "support",
"TelephoneNumber": "",
"MobileNumber": "",
"Culture": "en-GB",
"Timezone": "UTC", 
"UserGroups": ["Group 1", "Group 2", "Group 3"],
"EnableLogin": true,
"Isexternallymanaged": true
}]

Note: Remove "Isexternallymanaged" for non-SSO users.

6.5 Multiple users (non-SSO users)

[{ 
"Email": "test.user@ideagen.com",
"status": 0,
"Forename": "Test",
"Surname": "user",
"UserName": "Test.User",
"JobTitle": "I am a Test User",
"OrganisationalUnit": "3a7e9387-3996-469f-b1d1-1edc5e9eba54",
"ExternalId": "test.user@ideagen.com",
"ProviderId": "",
"TelephoneNumber": "",
"MobileNumber": "",
"Culture": "en-GB",
"Timezone": "UTC", 
"UserGroups": ["Group 1", "Group 2", "Group 3"],
"EnableLogin": true,
},
{ 
"Email": "test2.user@ideagen.com",
"status": 0,
"Forename": "Test 2",
"Surname": "user",
"UserName": "Test2.User",
"JobTitle": "I am a Test 2 User",
"OrganisationalUnit": "3a7e9387-3996-469f-b1d1-1edc5e9eba54",
"ExternalId": "test2.user@ideagen.com",
"ProviderId": "",
"TelephoneNumber": "",
"MobileNumber": "",
"Culture": "en-GB",
"Timezone": "UTC", 
"UserGroups": ["Group 1", "Group 2", "Group 3"],
"EnableLogin": true,
}]

Note: Add "Isexternallymanaged" for SSO users.

7. Creating a CSV file

The user sync file must be in JSON format and meet the JSON standard to be uploaded. However, some customers find it easier to input user data into a CSV file and then convert this into a JSON file before uploading to the S3 bucket.

If you cannot provide a JSON file, Ideagen Technical Services can, with additional effort, transform this data prior to import or sync.

Important: An example of a user import CSV file before conversion to JSON is attached to this article. This is for internal use only. Customers who require this will have been provided a copy by Technical Services.

8. Uploading a user sync file

To upload your JSON file, follow these steps:

1. Navigate to the S3 location provided to you.
2. Access the customer-integration-feed bucket.
3. Open the folder named <tenant name>/usersync.
4. Upload your JSON file to this location.

Important: The user data and the upload of the JSON file is your responsibility to manage and maintain.

9. Troubleshooting user sync failures

The sync file can fail in two locations: during file validation or after validation passes.

9.1 File validation

The first failure point is during the file validation phase. This checks the JSON is well-formed and all mandatory fields are present. It also validates fields such as Org Unit and Email to ensure they are correctly formatted and the values exist. Should validation fail at any point, the entire sync file will be rejected.

Note: A failed import email will not be sent out at this point.

The following examples show incorrectly formatted JSON files:

9.2 Example 1: Missing comma between curly brackets

"UserGroups": ["Group 1", "Group 2", "Group 3"],
"EnableLogin": true,
}
{ 
"Email": "test2.user@ideagen.com",
"status": 0,

Answer: Missing comma between the curly brackets. },{

9.3 Example 2: Missing square brackets around group names

"UserGroups": "Group 1", "Group 2", "Group 3",

Answer: Missing square brackets around the group names. ["Group 1", "Group 2", "Group 3"],

9.4 Example 3: Missing closing square bracket

"UserGroups": ["Group 1", "Group 2", "Group 3"],
"EnableLogin": true,
}

Answer: Missing square bracket to close the command. }]

Important: The above examples are incorrectly formatted on purpose to show what to look out for in a JSON file.

9.5 Validation passes

If validation passes, the system will start to sync each user. The sync can still fail at this point, but it will be on a per-user basis. The most common failure is that username or email already exists. This individual user will fail, but the process for the remaining users will continue. When failure occurs, an email is sent to you and the Ideagen Aviation Safety (Cora) Support team.