User Fields in Rally via API

[Sheri Moore]

We currently have an integration with Okta which creates and updates users using the API Key.  I would like to know if there is a list of fields that are required to be set in order for the user to be created successfully.  Is the list of field different than when they are created through the UI?  Thanks in advance for any insight!

------------------------------
SHERI L. MOORE | SENIOR PRODUCT MANAGER
ENTERPRISE PROGRAM MANAGEMENT OFFICE (ePMO)
AMERICAN EXPRESS
TRCN | 19640 N. 31st Avenue, MC: 18-02-01 | Phoenix, AZ 85027
O: 602766-1656 | E: [e-mail]
------------------------------

[Sagi Gabay]

Hi Sheri.

The short answer is that the minimal set of required fields are: "username" and "emailaddress". There are additional required fields but they have default value so they're not part of the minimal set. 

The easiest way to find out the required fields is for a sub-admin to get into the setup area, then Subscription settings, then click Fields, select 'User' from the drop-down. Then, you'll get the list of all User fields and you can find all required fields. The only required fields that have no default values are 'username' and 'emailaddress' so you must set them. The other required fields, if not explicitly set, will set to their default values.

With regard to your question of the API: 
It's the same set of fields, there aren't additional required fields by the API. If you wanted to find it out on your own what you can do is check out the WSAPI documentation page. You find the 'User' object on the bottom-left under the Object Model section. You can then scroll down the list of Child Elements and go over all fields. You can look for "Required = true" and this way find the required fields. I've included an attachment screenshot of the EmailAddress field definition where you can see it.

Now, there isn't a way to know if there is a default value or not. So in order to be certain what the minimal set of required fields is, and if you wanted to try it from the API, then you can use a tool such as Postman and try a few JSON datasets, where you can find out that omitting some of these required fields (such as Language or Locale) is okay, and you can see they're still getting set. Here's an example of a JSON that has all required field beyond the minimal set:

{
"User":
{
"username":"[e-mail]",
"emailAddress": "[e-mail]",
"Language": "en-US",
"Locale": "en-US",
"SubscriptionID": "209"
}
}


Let us know if helped.

Sagi

[Sheri Moore]

Thank you so much for all the details information, this really helps!  When I create a new user through the UI, there are certain fields that have a check box and by default it is unchecked.  These wouldn't appear to be required fields, but since the value is already set to false, could it be that they are required?  The API Documentation shows for example, planner is not required, but if we don't explicitly set that value, it tends to be set to false, even it was in the system as true.  We're trying to figure out why the Okta integration is setting certain fields.  We also found this to be true for network ID which is not a boolean field.

------------------------------
SHERI L. MOORE | SENIOR PRODUCT MANAGER
ENTERPRISE PROGRAM MANAGEMENT OFFICE (ePMO)
AMERICAN EXPRESS
TRCN | 19640 N. 31st Avenue, MC: 18-02-01 | Phoenix, AZ 85027
O: 602766-1656 | E: [e-mail]
------------------------------

[Sagi Gabay]

Hi Shei,

Thanks for following up and providing more info. Planner is not a required field, as you found. But since it's a Boolean type then 'False' is its default value. The UI will have this checkbox not checked as default, then you can check it. So, if you left it unchanged then it'll be saved as a 'False' value. Similarly the api will set it to 'False' unless it is explicitly set to 'True'. 

It sounds like the Okta integration is explicitly setting it. Do you have their code or can you follow up with them to learn what fields they're setting?
If you find users created with this value being 'True' then it would seem they are setting it. Perhaps they're using some user as a prototype, then initiating a copy of that user object where the Planner was set?  it's just a guess. You may want to connect with them to find out what is the data they're providing us in the JSON payload when creating a user and how they created that payload.

Sagi

[Sheri Moore]

Hi Sagi, Okta is not explicitly setting the value and we've been trying to troubleshoot the field since it's not being passed, but it is getting updated in Rally during updates.  We have found other fields that are getting set as well that they are not passing, so the assumption is that Rally is setting these values.  

This was their response to us - 

I confirmed with my App Developer team that the attribute in question can be turned on, but it's actually brought in from an import sync from Rally and not generated by Okta from the start. It is set as a true/false value only that is set within the Rally profile and passed down.

So, if the data is getting imported from Rally and the value is set to False when it's imported, if it gets changed in Rally, this imported value seems to overwrite the update in Rally that was made.  Does that seem logical?

------------------------------
SHERI L. MOORE | SENIOR PRODUCT MANAGER
ENTERPRISE PROGRAM MANAGEMENT OFFICE (ePMO)
AMERICAN EXPRESS
TRCN | 19640 N. 31st Avenue, MC: 18-02-01 | Phoenix, AZ 85027
O: 602766-1656 | E: [e-mail]
------------------------------