How to install and use UserSync plugin
UserSync plugin enables system administrators to define copy rules, which automates user copying between applications. Defining copy rules can be very useful when you want users of an application to be moved to another application automatically or if you want specific types of users to be collected in an overview application. This guide explains how to install and use the UserSync Plugin.
How to install or upgrade the plugin
- Login to SiteAdmin.
- Go to the Plugins tab.
- Set the Repository URL to http://update.gpsgate.com
- Under My Plugins tab, make sure Patch.v4 plugin is installed and up to date.
- Click on Get More Plugins.
- Download and install UserSync.
- Go to the Applications tab, you can access the plugin page by clicking Sharing Users from the side menu.
If you had already installed the UserSync plugin, make sure you have the latest version and there is no upgrades on the http://update.gpsgate.com repository.
Creating a copy rule
When you get to the plugin page for the first time, the page will show an information message telling that there are no copy rules defined. Please click the button “Create New” in the top right of the screen to get to the creating copy rules form.
After you fill in the Name and the Description (optional), you have to pick the source criteria for your copy rule.
Here, you have to fill in:
- From Application: Source application from which the users will be copied. Selecting ANY means that all users from all applications will be copied to target.
- From Role: When the copy rule is executed, only users in this role will be copied.
- From Tag: Only users having this tag will be copied when the copy rule is executed. ANY means users with any tag will be copied.
The steps above let you define the source of the copy rule. You must then pick the target criteria for the copy rule:
- To Application: The target application you want users to be copied to.
- To Role: The role you want users to have in the target application.
- To Tag: The tag you want users to have in the target application.
The last step is to specify the status of the copy rule:
- Active: Specifies if the copy rule is active or not. If you set this to RUNNING, the rule will be executed right away after saving.
- Synchronize when a user is deleted: By default, users are not deleted from the target application when they are removed from the source. Check this if you want users to be deleted from target application when they are removed from source application.
Please note that you have some limitations when creating a rule. Those are:
- You cannot pick a Role or Tag as source if it has already been picked as target in another rule.
- The target Role or Tag cannot be picked from those that are used as source in any of the previous rules.
Viewing and editing copy rules
After saving the copy rule successfully, you will be taken to the main page of the plugin, where you can see all the copy rules defined. By clicking any of these items, you will get to the edit form, where you can change the details of your copy rule.
How it works
If you set the status of a copy rule to RUNNING, it will be be executed for the first time right after saving. As long as a copy rule is active, it listens to changes to its source application and takes the necessary actions in the target. Below are the cases which trigger a copy rule:
- User is added to source application: If the new user’s roles and tags match any active copy rule, then this rule will be executed, and the user will be copied to the target application.
- Role/Tag changes of a user: If you change the roles/tags of a user (i.e. add or remove roles/tags) in the source application, the system checks if there are any matching active rules with user’s new roles/tags set, and execute any matching copy rules.
- Application is removed: When you remove an application, all the active copy rules having that particular application as their source will be executed. This process will remove users from the target applications only if Synchronize when a user is deleted was enabled for the copy rule.
Please note that passive rules are ignored when the cases above are handled.
Imagine you have five applications and each application has a few users with tracking devices. If you want to monitor all users in an overview application and you still want to keep the users in their original applications, you can define a copy rule to copy all users to the overview application.
By defining the rule as seen above, all users will continue residing under their original applications, as well as the overview application. Whenever a new user is added to the original application, it will be copied over to the overview application automatically. As stated above, a user will be removed from overview application only if Synchronize when a user is deleted is enabled for the copy rule.
Important note: If a user resides under two applications in some way, it won’t be deleted from the overview application unless it’s removed from both of the applications.
Discuss this blog post on the forum please