Web API - User and Profile Sync
This document will help you to configure profile sync via User Source. Before you continue, you need to make sure you have a valid license and configuration on your MonoSign Management Portal.
š Instructions
This documentation will contain 3 main steps and 7 optional step for integration.
You need to login with ārootā user to management portal.
Go to āDirectoryā => āSourcesā from left menu.
Go to āAny Source from the Listā by clicking the source name (If any User Source created)
Click the āSettingsā button in the upper right corner.
Create a new User Source by reading Create a New User Source document. (If User Source is not created). After User Source Created, please Go to āUser Sourceā by clicking the source name that just created.
Click the āSettingsā button in the upper right corner.
Configure Source Settings for Profile Sync
Configure āGeneralā Tab
Configure āUserā Tab
Configure āUser Groupsā Tab
Configure āGroupsā Tab
Configure āAuthenticationā Tab
Configure āMappingsā Tab
Configure āPasswordā Tab
Only Admin Users can make changes to āSourceā configuration.
If there is no User Source defined or User Source Settings is not configured before. Admin can continue to Step 2. But if there is a User Source defined or User Source Settings is configured before, admin user can jump into āStep 3 - d. Configure Mappings Tabā section and complete the profile sync via User Source.
Once āStep 3 - d. Configure Mappings Tabā section completed, please click āSaveā button and then start User Source Sync in Full mode.
To start User Source Sync in full mode, go to Edit Source page and activate āEnable Auto Syncā button and click āSaveā button. The Source will start the sync in a full mode in next run.
Step 2 - Navigating to User Source Settings
Once admin navigated to User Source Settings, admin will see a configuration page as shown below.
Navigate To User Source Settings 1
Once admin navigated to User Source Settings, admin will see a configuration page as shown below.
Navigate To User Source Settings 2
User Source Settings
Step 3 - Configure Source Settings for Profile Sync
You can see an example User Source Settings configurations for User Web API below. Letās start with configuring āGeneral Tabā.
a. Configure General Tab
User Source General Settings Configurations 1
User Source General Settings Configurations 2
Before you continue to configure settings, letās see an example of an Web API and configure the settings based on the Web API.
You can see an example of our sample Web API response below.
Sample Web API we will use is capable of listing Users by paging. You can select Use Paging option if your API works by paging.
Sample Web API Response
General Fields | Description |
|---|---|
Users Web API Url (Mandatory) | Defines the URL will be used fetching Users |
Request Method (Mandatory) | Defines which request method will be used fetching Users. You can use GET and POST method to fetch Users from API  Fetch Users |
Parameters Type (Mandatory) | Defines that parameter type will be used fetching Users. For Example: If you are using GET request method to fetch users, you should select QueryString parameter type. If you are using POST request method to fetch users, you should select Body parameter type.  Parameters Type |
Item Column | Defines the Item Column of your response body. For Example: In the response body, our Item Column key is ādataā  Item Column Example You can define āItem Columnā based on your response body. |
Use Paging (Optional) | Defines if MonoSign will fetch users by paging. If your Web API does not support paging, you can unselect āUse Pagingā option and you can skip filling āPage Count Column, Current Page Column, Item Per Page Count Column, Item Per Page Count Query Column Name, Current Page Query Column Name and Item Count Column columnsā |
Page Count Column (Mandatory if Use Paging Enabled) | Defines how many pages Web API will serve. The Page Count Column information needs to serve in the response body. |
Item Per Page Count Query Column Name (Mandatory if Use Paging Enabled) | Defines the column name that how many items will be serve per page. For example: In our sample API, limit is the Item Per Page Count Query Column Name.  Item Per Page Count Query Column Name You can define āItem Per Page Count Query Column Nameā based on your API behavior. |
Current Page Query Column Name (Mandatory if Use Paging Enabled) | Defines the column name that which page is fetching. For example: In our sample API, page is the Current Page Query Column Name.  Current Page Query Column Name You can define āCurrent Page Query Column Nameā based on your API behavior. |
Identity Column (Mandatory) | Defines the Identity column of each item from API response. For Example: In our sample API, id is the Identity Column for each user.  Identity Column |
User Name Column (Mandatory) | Defines the User Name Column of each item from API response. For Example: In our sample API, data.userName is the User Name Column.  User Name Column |
Email Column (Optional) | Defines the Email Column of each item from API response. Sample API does not include email field. If your API response includes please define the Email column based on your scenario. |
Connection Timeout (Optional) | Defines the connection timeout for User Source (in seconds) |
Headers (Optional) | Defines the headers if API requires header in the request. For Example: Letās assume that your API working with API Key. The API Key must be sent in the request as header. You can use this field to send headers in the request.  Headers |
Item Count (Mandatory if Use Paging is Enabled) | Defines the count of how many items will be listed in one page based on your API. Letās assume your page item count limit is 10. You need to specify this field based on your Web API. For Example: Sample API item count limit is 10. If you specify the field as 10, request URL will be like as shown.  Item Count |
Search Filter Key (Optional) | Defines the Search Filter Key if your API supports filter with a pattern. For Example: Letās assume your APIās search filter key is āidā and your filter key needs a pattern for searching items. When you specify key and pattern at the same time, your request URL will be like as shown. http://localhost:3000/users_for_profile_sync?id={YourFilterPattern} |
Search Filter Pattern for Full (Optional) | Defines the Search Filter Pattern for Full Sync if your API supports filter with a pattern. For Example: Letās assume your APIās search filter key is āidā and your filter key needs a pattern for searching items. When you specify key and pattern at the same time, your request URL will be like as shown. http://localhost:3000/users_for_profile_sync?id={YourFilterPatternForFullSync} |
Search Filter Pattern for Incremental (Optional) | Defines the Search Filter Pattern for Incremental Sync if your API supports filter with a pattern. For Example: Letās assume your APIās search filter key is āidā and your filter key needs a pattern for searching items. When you specify key and pattern at the same time, your request URL will be like as shown. http://localhost:3000/users_for_profile_sync?id={YourFilterPatternForIncrementalSync} |
Search Filter Parameters Type Method (Optional) | Defines that parameter type will be used fetching Users with search filter key and pattern. |
When Changed Date Format (Optional) | Defines the Date Format if your API supports listing only updated items. For Example: Letās assume your API supports listing only updated items with a key named āupdatedDateā. You can type which date format you API supports such as āyyyy-MM-ddTHH:mm:ssā. MonoSign will format the {{WhenChaned}} date to specified date format. |
Profile Identity Property (Optional) | If you want to bind this value to your profile information, type your property name. |
When the admin fills all the required configuration, admin can test if the configurations and connection is correct by clicking āTestā button in the lower right corner.
If admin sees a modal with the green section as shown below, everything seems correct for the general settings.
User Source General Settings Configuration Test
b. Configure User Tab
The User tab is only used to sync a user from the source. If your Web API does not support fetching only one item, you can skip this part.
User Tab includes optional configurations for User Sync. If the source is going to be used only syncing data to MonoSign and Password Management wants be managed by MonoSign, you donāt have to configure this tab. But if the Web API will manage the password, you need to configure User Tab.
User Source User Settings Configuration
User Fields | Description |
|---|---|
Sample User Id | Defines the Sample User Id for testing the User Info By Id. The first item's UserId from the API response can be typed. For Example:  First Itemās Id |
User Web Api Url | Defines the Web API URL of single user to be sync. For Example: http://localhost:3000/users_for_profile_sync/{{Id}} In our sample API, {{Id}} will be replaced to āidā property value of the API response. |
User Request Method | Defines which request method will be used fetching Users. You can use GET and POST method to fetch Users from API  Request Method |
User Connection Timeout | Defines the connection timeout for User Source (in seconds) |
User Identity Column | Defines the Identity column of each item from API response. For Example: In our sample API, id is the Identity Column for each user. |
User Item Column | Defines the Item Column of your response body. For Example: In the response body, our Item Column key is ādataā Item Column Example You can define āItem Columnā based on your response body. |
User Headers | Defines the headers if API requires header in the request. For Example: Letās assume that your API working with API Key. The API Key must be sent in the request as header. You can use this field to send headers in the request. Headers |
User Search Filter Key | Defines the Search Filter Key if your API supports filter with a pattern. For Example: Letās assume your APIās search filter key is āidā and your filter key needs a pattern for searching items. When you specify key and pattern at the same time, your request URL will be like as shown. http://localhost:3000/users_for_profile_sync?id={YourFilterPattern} |
User Search Filter Pattern | Defines the Search Filter Pattern for Sync if your API supports filter with a pattern. For Example: Letās assume your APIās search filter key is āidā and your filter key needs a pattern for searching items. When you specify key and pattern at the same time, your request URL will be like as shown. http://localhost:3000/users_for_profile_sync?id={YourFilterPatternForSync} |
User Search Filter Parameters Type Method | Defines that parameter type will be used fetching Users with search filter key and pattern. |
c. Configure User Groups Tab
The User Groups tab is used to sync a user to group comes from Web API. If your Web API does not present user groups, you can skip this part.
Before you continue to configure settings, letās see an example of an Web API and configure the settings based on the Web API.
You can see an example of our sample Web API response below.
Sample Web API we will use is capable of listing User Groups. If your API presents only Group Definitions, you can create an Automation on MonoSign to sync users to groups.
User Groups Tab Settings
In our sample API, user groups will be listed by departmentId. We will be configuring settings based on the APIās behaviour.
User Groups By DepartmentId
User Group Fields | Description |
|---|---|
Add User Groups | Defines if User Groups will be synced to MonoSign |
User Groups Web API Url | Defines the URL will be used fetching Userās Groups. |
User Groups Web API Request Method | Defines which request method will be used fetching Userās Groups. You can use GET and POST method to fetch User's Groups from API.  User Groups Web API Request Method |
User Groups Web API Parameters Type | Defines that parameter type will be used fetching User's Groups. For Example: If you are using GET request method to fetch userās groups, you should select QueryString parameter type. If you are using POST request method to fetch user's groups, you should select Body parameter type.  User Groups Web API Parameters Type |
User Groups Web API Connection Timeout | Defines the connection timeout for User Source (in seconds) |
User Groups Web API Identity Column | Defines the Identity column of each group item from API response. For Example: In our sample API, id is the Identity Column for each user group.  User Groups Web API Identity Column |
User Groups Web API Identity Column For User Match | Defines the Identity column for User Match of each group item from API response. For Example: In our sample User Groups Web API, ādepartmentIdā property will be the identity column that matches the User Web API identity column as shown below.  User Group Web API Identity Column For User Match |
User Web API Identity Column For User Group Match | Defines which user property will match the user group in the user group Web API. For Example: In our sample User Web API, ādepartmentIdā property will be the identity column that matches the User Group Web API identity column as shown above.  User Web API Identity Column For User Group Match |
User Groups Web API Name Column (Mandatory) | Defines the User Group Name column |
User Groups Web API Title Column (Mandatory) | Defines the User Group Name column |
User Groups Web API Parameters Pattern | Defines the User Groups Web API Parameters Pattern for User Groups Search. It can be used if only āUser Groups Web Api Parameters Typeā selected as QueryStringPattern. For Example:  User Groups Web API Parameters Pattern In the pattern, {{departmentId}} will be replaced to āUser Web API Identity Column For User Group Matchā property value. You can see and example URL finalized down below. http://localhost:3000/groups_for_profile_sync?departmentId=00001 |
User Groups Web API Use Paging | Defines if MonoSign will fetch users by paging. If your User Group Web API does not support paging, you can unselect āUse Pagingā option and you can skip filling āUser Groups Web Api Page Count Column, User Groups Web Api Current Page Column, User Groups Web Api Item Per Page Count Column, User Groups Web Api Current Page Query Column Name, User Groups Web Api Item Per Page Count Query Column Name and User Groups Web Api Item Count Column columnsā |
User Groups Web API Item Column | Defines the Item Column of your response body. For Example: In the response body, our Item Column key is the objectās itself. If your response is like as shown below, you can leave it empty.  User Groups Web API Item Column |
User Groups Web Api Page Count Column | Defines how many pages Web API will serve. The Page Count Column information needs to serve in the response body. |
User Groups Web Api Current Page Query Column Name | Defines the column name that which page is fetching. For example: In our sample API, page is the User Groups Web Api Current Page Query Column Name.  User Groups Web Api Current Page Query Column Name You can define āUser Groups Web Api Current Page Query Column Nameā based on your API behavior. |
User Groups Web Api Item Per Page Count Query Column Name | Defines the column name that how many items will be serve per page. For example: In our sample API, limit is the User Groups Web Api Item Per Page Count Query Column Name.  User Groups Web Api Item Per Page Count Query Column Name You can define āUser Groups Web Api Item Per Page Count Query Column Nameā based on your API behavior. |
User Groups Web Api Item Count | Defines the count of how many items will be listed in one page based on your API. Letās assume your page item count limit is 10. You need to specify this field based on your Web API. For Example: Sample API item count limit is 10. If you specify the field as 10, request URL will be like as shown.  User Groups Web Api Item Count |
User Groups Search Filter Pattern | Defines the Search Filter Pattern if your API supports filter with a pattern. For Example: Letās assume your APIās search filter key is ādepartmentIdā and your filter key needs a pattern for searching items. When you specify key and pattern at the same time, your request URL will be like as shown. http://localhost:3000/groups_for_profile_sync?departmentId={YourFilterPatternForUserGroup} |
User Groups When Changed Date Format | Defines the Date Format if your API supports listing only updated items. For Example: Letās assume your API supports listing only updated items with a key named āupdatedDateā. You can type which date format you API supports such as āyyyy-MM-ddTHH:mm:ssā. MonoSign will format the {{WhenChaned}} date to specified date format. |
User Groups Search Filter Key | Defines the Search Filter Key if your API supports filter with a pattern. For Example: Letās assume your APIās search filter key is āidā and your filter key needs a pattern for searching items. When you specify key and pattern at the same time, your request URL will be like as shown. http://localhost:3000/groups_for_profile_sync?departmentId={YourFilterPattern} |
User Groups Search Filter Parameters Type Method | Defines that parameter type will be used fetching User Groups with search filter key and pattern. |
User Groups Headers | Defines the headers if API requires header in the request. For Example: Letās assume that your API working with API Key. The API Key must be sent in the request as header. You can use this field to send headers in the request. Headers |
d. Configure Groups Tab
The Groups tab is used to sync Groups. If your Web API does not present groups, you can skip this part.
Before you continue to configure settings, letās see an example of an Web API and configure the settings based on the Web API.
Groups Tab Settings
Groups Web API
You can see an example of our sample Web API response below.
Sample Web API we will use is capable of listing Group Definitions. If your API presents only Group Definitions, you will see the group definitions on Groups page on MonoSign.
We will be configuring settings based on the APIās behaviour.
Groups' Fields | Description |
|---|---|
Groups Web Api Url | Defines the Web API URL of groups to be sync. For Example: http://localhost:3000/groups_for_profile_sync |
Groups Web Api Request Method | Defines which request method will be used fetching Groups. You can use GET and POST method to fetch Groups from API  Groups Web Api Request Method |
Groups Web Api Parameters Type | Defines that parameter type will be used fetching Groups. For Example: If you are using GET request method to fetch groups, you should select QueryString parameter type. If you are using POST request method to fetch groups, you should select Body parameter type.  Groups Web Api Parameters Type |
Groups Web Api Connection Timeout | Defines the connection timeout. (in seconds) |
Groups Web Api Use Paging | Defines if MonoSign will fetch groups by paging. If your Web API does not support paging, you can unselect āUse Pagingā option and you can skip filling āGroups Web Api Page Count Column, Groups Web Api Current Page Query Column Name and Groups Web Api Item Per Page Count Query Column Name columnsā |
Groups Web Api Item Column | Defines the Item Column of your response body. For Example: In the response body, our Item Column key is the objectās itself. If your response is like as shown below, you can leave it empty. Groups Web API Item Column |
Groups Web Api Page Count Column | Defines how many pages Web API will serve. The Page Count Column information needs to serve in the response body. |
Groups Web Api Current Page Query Column Name | Defines the column name that which page is fetching. For example: In our sample API, page is the Groups Web Api Current Page Query Column Name. Groups Web Api Current Page Query Column Name You can define āGroups Web Api Current Page Query Column Nameā based on your API behavior. |
Groups Web Api Item Per Page Count Query Column Name | Defines the column name that how many items will be serve per page. For example: In our sample API, limit is the Groups Web Api Item Per Page Count Query Column Name. Groups Web Api Item Per Page Count Query Column Name You can define āGroups Web Api Item Per Page Count Query Column Nameā based on your API behavior. |
Groups Web Api Item Count | Defines the count of how many items will be listed in one page based on your API. Letās assume your page item count limit is 10. You need to specify this field based on your Web API. For Example: Sample API item count limit is 10. If you specify the field as 10, request URL will be like as shown. Groups Web Api Item Count |
Groups Web Api Identity Column | Defines the Identity column of each group item from API response. For Example: In our sample API, id is the Identity Column for each group. Groups Web Api Identity Column |
Groups Web Api Name Column (Mandatory) | Defines the Group Name column |
Groups Web Api Title Column (Mandatory) | Defines the Group Title column |
Groups Web Api Search Filter Pattern | Defines the Search Filter Pattern if your API supports filter with a pattern. For Example: Letās assume your APIās search filter key is āidā and your filter key needs a pattern for searching items. When you specify key and pattern at the same time, your request URL will be like as shown. http://localhost:3000/groups_for_profile_sync?id={YourFilterPatternForGroup} |
Groups Web Api When Changed Date Format | Defines the Date Format if your API supports listing only updated items. For Example: Letās assume your API supports listing only updated items with a key named āupdatedDateā. You can type which date format you API supports such as āyyyy-MM-ddTHH:mm:ssā. MonoSign will format the {{WhenChaned}} date to specified date format. |
Groups Web Api Search Filter Parameters Type Method | Defines that parameter type will be used fetching Groups with search filter key and pattern. |
Groups Web Api Search Filter Key | Defines the Search Filter Key if your API supports filter with a pattern. For Example: Letās assume your APIās search filter key is āidā and your filter key needs a pattern for searching items. When you specify key and pattern at the same time, your request URL will be like as shown. http://localhost:3000/groups_for_profile_sync?id={YourFilterPatternForGroup} |
Groups Web Api Headers | Defines the headers if API requires header in the request. For Example: Letās assume that your API working with API Key. The API Key must be sent in the request as header. You can use this field to send headers in the request. Headers |
Group Web Api Url | Defines the Web API URL of single group to be sync. For Example: http://localhost:3000/groups_for_profile_sync/{{Id}} In our sample API, {{Id}} will be replaced to āidā property value of the API response. http://localhost:3000/groups_for_profile_sync/fb3f2013-2025-4403-89c6-81e8d7f4d64f |
Group Web Api Request Method | Defines which request method will be used fetching single Group. You can use GET and POST method to fetch group from API  Group Web Api Request Method |
Group Web Api Connection Timeout | Defines the connection timeout. (in seconds) |
Group Web Api Identity Column | Defines the Identity column of group from API response. For Example: In our sample API, id is the Group Web Api Identity Column for each user.  Group Web Api Identity Column |
Group Web Api Item Column | Defines the Item Column of your response body. For Example: In the response body, our Item Column key is the objectās itself. If your response is like as shown below, you can leave it empty. User Groups Web API Item Column |
Group Web Api Headers | Defines the headers if API requires header in the request. For Example: Letās assume that your API working with API Key. The API Key must be sent in the request as header. You can use this field to send headers in the request. Headers |
e. Configure Authentication Tab
The Authentication tab is only used if your User Source allows to User Login.
If your User Source does not support User Login, you need to select Password Management by MonoSign on User Source Detail page.
Authentication Tab Settings
Authentication Fields | Description |
|---|---|
Endpoint Url | Defines the Endpoint Url for User Authentication to MonoSign. For Example: http://localhost:3000/login |
Request Method | Defines which request method will be used for User Login.  User Login Request Method |
Request Timeout | Defines the request timeout of User Login API (in seconds) |
Request Headers | Defines the headers if API requires header in the request.  Request Headers |
Request Body | Defines the body of API request. Letās assume your Login Endpoint requires username and password in the request body. You can see an example of Sample Web API request body below. For Example:  Request Body |
You can see a postman example of Sample User Login API down below.
Sample User Login Endpoint
As you can see, if username and password is correct, Sample User Login API response will be shown above.
f. Configure āMappingsā Tab
Mappings configuration is used to sync user profile properties from the User Source properties.
In this section we will be able to sync User Web API attribute/property values to MonoSign user created by Web API User Source.
You can see an example of Web API User attributes/properties down below.
Web API User Source attributes/properties
You can see an example of MonoSign User attributes/properties down below created before.
MonoSign Attributes/Properties
If there is no property created on MonoSign, admin can create Profile Property by reading the documentation.
For an example:
birthDate, motherName, fatherName, identityNumber, gender and departmentId web api attribute/property values will be mapped to BirthDate, MotherName, FatherName, IdentityNumber, Gender and Department MonoSign attribute/property values.
Admin can change configuration on the Source Settings Mapping Configuration as shown. You can see an example below.
User Source Settings Mappings
g. Configure āPasswordā Tab
Password Settings configurations is used for override the Web API User Source password policy. Web API User Provider does not support changing User Password. You can skip this part.
Once all the settings completed on User Source Settings please check all the fields and then click the āSaveā button and Start User Source Sync in Full mode.
To start User Source Sync in full mode, go to Edit Source page and activate āEnable Auto Syncā button and click āSaveā button. The Source will start the sync in a full mode in next run.
Full Sync Mode will create/update Users from Web API and Full Sync Mode will create/update profile property values on MonoSign.
When User Source Full Sync completed, you can check your source users and users' profile property values.
To check Users, Groups and User Profile Property values, please follow the steps.
For user check.
Go to Directory ā Users
Search your user such as āakristeenā
If you see a screen with user as shown, it means user sync completed via User Source.
User via Web API HR Users
For group check.
Go to Directory ā Groups
Select āWeb API HR Usersā source filter to list and check if groups synced properly.
If you see a screen with user as shown, it means groups sync completed via User Source.
Groups via Web API HR Groups
For user profile property value check.
Go to Directory ā Profiles
Search your user such as āakristeenā.
Click your username on the list and view user profile
If you see a screen with profile property values as shown, it means profile sync completed via User Source.
User Profile Property Values
You have completed user sync and user profile sync via Web API User Source.