You are here: / / / Importing further OUs for user team leaders

Avendoo® online documentation

Importing further OUs for user team leaders

Background

You can nominate superiors automatically to user team leaders via the OUs of their employees in Avendoo®.
If a series of further user team leaders which are not superiors should be permitted via corresponding OUs, you can do that via the API endpoint “teamleaderOeImport”. In this way you can insert a list with OU permissions for user team leaders into the Avendoo® system.

To keep the OU permission of the team leaders up to date, you can execute the matching also regularly.

You can use the OU import also for giving additional OU permissions to user team leaders who got already automatically OU permissions, because they are superiors for example.

Use

Some customers need – besides the superiors as team leaders – further users who should see the other users in the team leader cockpit for register or deregister them to courses or to create reports via these users.

Examples: 

  • Setting up “education officer” (=persons who can register or deregister users to courses)
  • Setting up user team leaders in clients in which users are only manually recorded (via registration code for example) and no automatic matching of master data delivers a superior.

Prerequisites

  • There’s a system or process required which contains the data basis. From this sysstem or proces has to be generated a list with OU permissions for single users who should have access as user team leader in Avendoo®. Then you can compile the data in a manual process or you can determine the data as a request from a (HR-) system.
  • The CSV file with the columns “login” and “oe” ist required. The example file you find here.
    Important

    – You have to write the user names in the column “login” exactly in the same way like in the user account, for example no spaces at the end.
    – You can enter any lines (each with login;oe) per user who should get the OU permissions.
    – You can use also “wildcards” (% or underscroll) in the OU of the column “oe”.

  • An API author account for using the API (interface) in the Avendoo® system is required. This author should also get an own permission group. This API account needs the right Edit users and access to the corresponding client with the users.
    Optional prerequisite is an extra permission group if the user should get, besides the OU permission, further rights  or access to reports as user team leader. That permission group contains user team leader permissions and/or reports for user team leaders which are not included in the standard permission group. This permission group is not required if the standard permission group – which already got the users – contains all necessary user team leader rights.

Quick instruction

Create API author

To call the interface you need an Avendoo® author account. We recommend to create an account which is only used for the interface and not for any other purpose.

You should assign this author account a permission group which gives the API author the following permissions:

  • Show users
  • Create and edit users
  • Show, create and edit clients (required at this time)
    Access to the corresponding clients with the accounts of the user team leaders of whom the OU should be imported.

Create API interfaces call

For the setting up and the test use of the interface we use the program “Postman”. This program and its usage is  for visualizing. You use any REST API client for the final API call.

You can use also the function “code” in Postman to get PHP, cURL or Java script code with which the interface call can be done.

Endpoint API – teamleaderOeImport

The API call is a POST request, this means data is transferred for editing. The URL of the API endpoint is called: {{url}}/usergroup/{{userGroupId}}/teamleaderOeImport 

Fill out the placeholders in the double curly brackets with the matching values of your Avendoo® system.

url: This is the URL of your Avendoo® system with the path to the API (/api/v1). Enter the URL with „https://“ at the beginning.

userGroupId: This is the ID of the client in which the users are. The team leader OU permissions of these users should be adjusted. You get the client ID by choosing the menu entry Information in the context menu of the client. You can mark and copy the ID of the client by double click on the ID. It’s important to know that “_1” at the end belongs to the ID.
Example: 1641541269201_1

Enter Header parameters for the API request

Enter the following header parameters for the API request: 

Mandatory parameters
Key: Accept        
Value: application/xml

Optional parameters
Key:  userWithOeBecomeTeamleader
Value: true/false 

  • This parameter transfers normal user or learner accounts into user team leaders who can use the team leader cockpit. It’s possible to choose the value „false“ or „true“. We recommend „true“ because „false“ makes only sense if you want to give users who got alread team leader rights in Avendoo® only additional OU permissions. In this case you can also leave out this parameter.

Key: permissionGroupId
Value: ID of a permission group

  • This is the ID of a permission group which should also get the user team leaders additionally. In this case you can assign a further permission group to the user team leaders besides the OU permissions. Thus you can give permissions by the import of the OUs which the team leader haven’t got before.

Enter CSV file in the REST client

Enter the CSV file in the REST client on “Body” as “form-data” and the value of the “key” file.

Code the CSV file for the Body

Note that a CSV file has to be coded in the “UTF-8” character set. It should never be a “UTF-8 BOM” file.

  • If you haven’t created the CSV file in Excel, it’s often a “UTF-8 BOM” file. In this case you have to open that CSV file with the normal Windows Editor or Notepad++. Then choose Save as and  the entry and value “UTF-8” in the drop down menu Coding.
  • If you work with Notepad ++, select the whole text and choose the menu entry Convert to UTF-8 in the menu Coding. Finally, you save the file.

Execute API call send

After you’ve completed the configuration you can test the interface call.

  • If you’ve configured all parameters correctly you get the HTTP status message “200” for okay.
  • If the matching permissions are not set you get the HTTP status 403  for wrong permission.
  • If the URL of the API call got a typo you get the message error 404 for „not found“, this means the endpoint is unknown.

Check imported team leader OU permissions

After the successful API call you can see the imported team leader OU permissions directly in the User wizard. They are shown on the tab Functions in the OU list.

Check if there is no “(auto)” behind the OUs and if these imported OUs are shown like the manual OU permissions.

Results and following activities

This interface is meant to be to synchronize regularly OUs for the favored user team leaders in the long run. If one of the user team leaders also get OU auto permissions because he/she is a superior, these auto OUs are not overwritten by the team leader OU import.

If you remove a login of a user team leader from the import file later, this means all lines of the user team leader are not in the current team leader OU import, all OU permissions set by the import are removed.

Thus you should always name all team leader OU permissions via this import. Furthermore you can not execute several various team leader OU import for the same client.

The OU permissions which are set by the team leader OU import before are the only ones which are reset. If there are also manually OU permissions directly in the User wizard there are no effects on them.