Skip to main content
Skip table of contents

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.

  1. You need to login with “root” user to management portal.

  2. Go to “Directory” => “Sources” from left menu.

    1. Go to “Any Source from the List“ by clicking the source name (If any User Source created)

      1. Click the “Settings“ button in the upper right corner.

    2. 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.

      1. Click the “Settings“ button in the upper right corner.

  3. Configure Source Settings for Profile Sync

    1. Configure “General“ Tab

    2. Configure “User“ Tab

    3. Configure “User Groups“ Tab

    4. Configure “Groups“ Tab

    5. Configure “Authentication“ Tab

    6. Configure “Mappings“ Tab

    7. 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.

http://localhost:3000/users_for_profile_sync/00001

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.

  1. Go to Directory → Users

  2. 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.

  1. Go to Directory → Groups

  2. 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.

  1. Go to Directory → Profiles

  2. Search your user such as “akristeen“.

  3. 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.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.