Add additional API params to Jobs > importUsers

[pinodex]

Changes

Added upsert and send_completion_email parameters to Jobs::importUsers.

References

Closes #353

Testing

Functionality can be tested by setting the upsert and send_completion_email boolean parameters for Jobs::importUsers. This should create a request which is compatible with the API docs of Auth0 Management V2 API: https://auth0.com/docs/api/management/v2#!/Jobs/post_users_imports

• This change adds test coverage

• This change has been tested on the latest version of PHP

Checklist

• I have read the Auth0 general contribution guidelines.

• I have read the Auth0 Code of Conduct.

• All existing and new tests complete without errors.

• The correct base branch is being used.

[joshcanhelp]

Thanks for this @pinodex! I'll pull this down and test it locally since we don't have tests written for this endpoint yet. Stay tuned!

[joshcanhelp]

Works great, just a change to the function signature and adding another option. Thank you!

[joshcanhelp]

We've got another optional parameter we can send, external_id. At this point, I think it would be better to pass those optional params in as an array to disambiguate the call and provide a way to add new params if that endpoints begins supporting more.

[pinodex]

I've added the array parameters. Can you see if it works?

[joshcanhelp]

Getting closer but I think we can do a better job of looking for the params we want out of this and making sure we have a reasonable value. Check if the allowed parameters - upsert, send_completion_email, external_id - are included and then get them to a useable value. This will help document expected values and hopefully avoid issues. Something like:

if ( isset( $params['upsert'] ) ) {
  $request->addFormParam('upsert', filter_var( $params['upsert'], FILTER_VALIDATE_BOOLEAN ));
}

if ( isset( $params['send_completion_email'] ) ) {
  $request->addFormParam('send_completion_email', filter_var( $params['send_completion_email'], FILTER_VALIDATE_BOOLEAN ));
}

if ( ! empty( $params['external_id'] ) && is_string( $params['external_id'] ) ) {
  $request->addFormParam('external_id', $params['external_id']);
}

[pinodex]

With that approach, would we still allow for new params to be passed if the endpoint begins supporting more like you mentioned earlier?

[joshcanhelp]

They would need to be added but our team is notified of any changes to the public API and will add them as they come up.

[pinodex]

I see. I've added the requested changes.

[joshcanhelp]

Thanks again, @pinodex! I'll pull this down tomorrow, test, and merge!

[joshcanhelp]

One last thing here and then I'll merge this in.

One thing to note ... the \Auth0\SDK\API\Helpers\RequestBuilder::addFormParam() method is not converting the boolean values to the string value that's required by the API (it's sending 1 instead, which the API is not interpreting as true). I'll need to make a change to the request builder for this to work properly, which I'll do a in separate PR.

[joshcanhelp]

It occurred to me that this is too restrictive and would lead to omitting int values. Let's remove that is_string check here.

[pinodex]

But shouldn't the external_id parameter supposed to be a string as defined in the API docs? https://auth0.com/docs/api/management/v2#!/Jobs/post_users_imports

[joshcanhelp]

The form is post as multipart, not JSON, so string and int are treated basically the same. I tested it out locally just to be sure and it submits an int external ID value just fine.

[pinodex]

I see. It still submit the parameter as a string. I've removed the check.

[joshcanhelp]

Thank you @pinodex!

[github-actions]

This pull request has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.