In the 18.09 release of EPM Cloud new functionality was added to provide the ability to manage users and roles at an identity domain level with EPM Automate or REST API. I covered this functionality in detail in a previous post which you can read all about here.
The EPM Automate commands added in that release were:
In this post I will quickly go through the commands, first with EPM Automate and then with the REST API.
Let us start with the “adduserstogroup” command.
The syntax for the EPM Automate command is:
epmautomate addUsersToGroup FILENAME GROUPNAME
Where FILENAME is a file containing a list of users that has already been uploaded to EPM cloud. GROUPNAME is the group you want to assign the users in the file to.
The users will need to exist in the identity domain, if they don’t you can add them with the “addusers” command. The users will also need to have an identity domain role applied, this can be achieved with the “assignroles” command.
I would have preferred it if you could specify the user and the group they should be assigned to in the file instead of only being able to assign a single group at a time.
I will go through an example to add the following user to a group.
The user has already been assigned an identity domain role.
The group to assign the user to already exists in “Access Control”.
The group does not currently have any users assigned to it.
To be able to use the EPM Automate command, you need a file containing the list of users to assign to a group.
Obviously you can include as many users as you like in the file.
The file must have the header “User Login” otherwise you will generate an error when trying to use the command.
Once the file has been produced it has to be uploaded to EPM Cloud, this can be achieved with the EPM Automate “uploadfile” command.
The file will then be available from the application “Inbox/Outbox Explorer”.
Now the file exists, the “addusertogroup” command can be executed to assign the users in the file to the group specified in the command.
The response from issuing the command will include how many users were processed, including the number of successful and failed group assignments.
Checking the group in "Access Control" confirms the user has been successfully assigned.
To remove users from a group is pretty much the same concept, only difference is this time it will be the command “removeusersfromgroup”. I am going to use the same user file and remove them from the same group.
The output will once again highlight how many users in the file were successfully or unsuccessfully removed from a group.
As the command successfully removed the user they have been unassigned in "Access Control".
If you try to run the command against a group that does not exist, then you will receive an error.
I did wonder whether the command would allow you to add a group to a group and not just users to a group.
Considering the header in the file has to specify “User Login” I wasn’t holding out much hope, anyway I added a group to the file and uploaded.
Running the command generated a failure.
It would be good if the command included a parameter to define where to assign users or groups to a group. This would be preferable over another new command.
Now on to achieving the same functionality with the REST API.
I am not going to go through uploading a file using the REST API again as I covered that in my previous post.
The REST API URL format for adding/removing users to/from groups is:
https://<cloud_instance>/interop/rest/security/v1/groups
To assign a group to the users contained in a file a PUT method is required, the body of the request should include the filename, the group name and a job type of “ADD_USERS_TO_GROUP”.
I said this in my previous post, but it is a shame that the user/group information could not have been included the body of the request instead of having to upload a file.
Using a rest client an example to assign users to a group is:
The response will contain job information for adding users to groups. A status of -1 means the job is in progress, a URL is included which then can be accessed to check the job status.
Using the URL from the response, a GET request can be made to keep checking the job status until it completes.
A status of 0 means the operation was successful, just as with EPM Automate details are included to inform how many assignments were processed and how many succeeded or failed.
As the details show the process was successful, the user in the file has been assigned to the group.
To remove users from a group is very similar, the only difference is the “jobtype” parameter which should be “REMOVE_USERS_FROM_GROUP”.
The response contains the same information as when using the resource to add users to a group.
The status can be checked until the job completes.
The user has now been removed the group.
To automate the process with the REST API and scripting you could put together something like:
The above script first tries to delete any existing file in EPM Cloud with the same name as the one that will be uploaded, once this is done, a file containing the list of users to assign a group to is uploaded.
The file will then be available from the applications “Inbox/Outbox Explorer”.
Next, the REST resource to add users to a group is called. The URL to check the job status is then extracted from the response. The job status is checked until it completes.
The user contained in the uploaded file has been successfully assigned to the specified group.
To remove users from a group the same script can be reused with the job type changed to “REMOVE_USERS_FROM_GROUP”.
I am sure I am going to get asked if it is possible to create a group with EPM Automate or the REST API, unfortunately there is no direct command to do this yet.
The EPM Automate commands added in that release were:
- addusers – Creates new users in the identity domain based on the contents of a comma separated file.
- removeusers – Deletes identity domain accounts based on the contents of a comma separated file.
- assignroles – Assigns an identity domain role to all users that are contained in a comma separated file.
- unassignroles – Unassigns an identity domain role to all users that are contained in a comma separated file.
- adduserstogroup -- Adds a batch of users contained in a file to an existing group in Access Control.
- removeusersfromgroup - Removes a batch of users contained in a file from an available group in Access Control.
In this post I will quickly go through the commands, first with EPM Automate and then with the REST API.
Let us start with the “adduserstogroup” command.
The syntax for the EPM Automate command is:
epmautomate addUsersToGroup FILENAME GROUPNAME
Where FILENAME is a file containing a list of users that has already been uploaded to EPM cloud. GROUPNAME is the group you want to assign the users in the file to.
The users will need to exist in the identity domain, if they don’t you can add them with the “addusers” command. The users will also need to have an identity domain role applied, this can be achieved with the “assignroles” command.
I would have preferred it if you could specify the user and the group they should be assigned to in the file instead of only being able to assign a single group at a time.
I will go through an example to add the following user to a group.
The user has already been assigned an identity domain role.
The group to assign the user to already exists in “Access Control”.
The group does not currently have any users assigned to it.
To be able to use the EPM Automate command, you need a file containing the list of users to assign to a group.
Obviously you can include as many users as you like in the file.
The file must have the header “User Login” otherwise you will generate an error when trying to use the command.
Once the file has been produced it has to be uploaded to EPM Cloud, this can be achieved with the EPM Automate “uploadfile” command.
The file will then be available from the application “Inbox/Outbox Explorer”.
Now the file exists, the “addusertogroup” command can be executed to assign the users in the file to the group specified in the command.
The response from issuing the command will include how many users were processed, including the number of successful and failed group assignments.
Checking the group in "Access Control" confirms the user has been successfully assigned.
To remove users from a group is pretty much the same concept, only difference is this time it will be the command “removeusersfromgroup”. I am going to use the same user file and remove them from the same group.
The output will once again highlight how many users in the file were successfully or unsuccessfully removed from a group.
As the command successfully removed the user they have been unassigned in "Access Control".
If you try to run the command against a group that does not exist, then you will receive an error.
I did wonder whether the command would allow you to add a group to a group and not just users to a group.
Considering the header in the file has to specify “User Login” I wasn’t holding out much hope, anyway I added a group to the file and uploaded.
Running the command generated a failure.
It would be good if the command included a parameter to define where to assign users or groups to a group. This would be preferable over another new command.
Now on to achieving the same functionality with the REST API.
I am not going to go through uploading a file using the REST API again as I covered that in my previous post.
The REST API URL format for adding/removing users to/from groups is:
https://<cloud_instance>/interop/rest/security/v1/groups
To assign a group to the users contained in a file a PUT method is required, the body of the request should include the filename, the group name and a job type of “ADD_USERS_TO_GROUP”.
I said this in my previous post, but it is a shame that the user/group information could not have been included the body of the request instead of having to upload a file.
Using a rest client an example to assign users to a group is:
The response will contain job information for adding users to groups. A status of -1 means the job is in progress, a URL is included which then can be accessed to check the job status.
Using the URL from the response, a GET request can be made to keep checking the job status until it completes.
A status of 0 means the operation was successful, just as with EPM Automate details are included to inform how many assignments were processed and how many succeeded or failed.
As the details show the process was successful, the user in the file has been assigned to the group.
To remove users from a group is very similar, the only difference is the “jobtype” parameter which should be “REMOVE_USERS_FROM_GROUP”.
The response contains the same information as when using the resource to add users to a group.
The status can be checked until the job completes.
The user has now been removed the group.
To automate the process with the REST API and scripting you could put together something like:
The above script first tries to delete any existing file in EPM Cloud with the same name as the one that will be uploaded, once this is done, a file containing the list of users to assign a group to is uploaded.
The file will then be available from the applications “Inbox/Outbox Explorer”.
Next, the REST resource to add users to a group is called. The URL to check the job status is then extracted from the response. The job status is checked until it completes.
The user contained in the uploaded file has been successfully assigned to the specified group.
To remove users from a group the same script can be reused with the job type changed to “REMOVE_USERS_FROM_GROUP”.
I am sure I am going to get asked if it is possible to create a group with EPM Automate or the REST API, unfortunately there is no direct command to do this yet.
No comments:
Post a Comment
Note: only a member of this blog may post a comment.