Skip to main content

Sales Portal user management tutorial

In this tutorial, you will use the Varicent Incentives REST APIs to enable new web users, lock and unlock web users, and reset passwords for web users.

Prerequisites

  1. You have imported payee data into the Payee table. For more information on adding data to tables, see ???.

  2. You have created Portal Access groups for the payees that you want to manage. For more information on creating Portal Access groups, see Portal Access Module.

  3. You have obtained your Varicent API Key as outlined in REST API authentication and headers.

Overview

In this tutorial, we will be using the following REST API calls to enable a group of new payees in a Portal Access group:

Get Portal Access group ID

This call gets the name of the table that contains the data that you want to modify.

Enable Portal Access group

This call uses the table name retrieved by the Get table name call to get the ID of the input form that contains the data that you want to modify.

Next, we will be using the following REST API call to lock and unlock a payee and reset a payee's password:

Update web user

This call updates a web user's information such as their password and lock status.

Retrieving the Portal Access group ID

First, use the Varicent Incentives REST API call to retrieve a list of all the Portal Access groups.

  1. Make the following request:

    GET /api/v1/portalaccessgroups

    For example,

    curl -X GET -H "Authorization: Bearer API_KEY" 
-H "Model: YOUR_CLIENT_MODEL” 
-H "Content-Type: application/json" 
https://YOUR_ICM10_API_SERVER_ADDRESS/api/v1/portalaccessgroups

    You can use the following parameter to filter the return response:

    Parameter

    Description

    filter

    The supported fields are:

    • groupName: the Portal Access group name.

    • groupId: the Portal Access group ID.

    The supported operations are:

    • Equal matching `name=admin`. This is strict and case-sensitive.

    • Starts with `name^admi`, or ends with `name$min`. This is case-insensitive.

    • Equal matching within a list, such as `userType=Admin\\,Web`. This is case-insensitive.

    • Interval matching, such as `date=[2015-09-22\\,2015-09-25]`, supports the mathematics notation for inclusive/exclusive bounds, `[a\\,b]`, `(a\\,b)`, or a mix `(a\\,b]`. Intervals also support open-ended bounds, `(a\\,]`.

    • Not equal matching `name<>admin`. This is strict and case-sensitive.

    • Is contained in `name⊇dmi`. This is case insensitive.

    • NULL checks, such as `name=NULL` or `name<>NULL`. Only equal and not equal operators are supported.

    You can use multiple filters on one attribute. The filter query also supports the use of an operator. Complete filter definitions, as described above, are expected on both sides of the operator. The column filtered must be the same on both sides of the operator. Supported operators are: AND `&&`, OR `||`.

    To define a filter on multiple attributes, separate each filter statement with `;`.

    The following is an example using the filter parameter:

    GET /api/v1/portalaccessgroups?filter=groupId=80

  2. In the response body, find the Portal Access group that contains the payees that you want to enable, and note the ID.

    [
    {   
        "comment": "",
        "group": {
            "definition": {
                "groupId": 2,
                "groupName": "Administrator" 
            },
            "isPasswordExpiryEnabled": false
    },
    "name": "Administrator",
    "passwordExpiryEnabled": false,
    "type": "Group",
    "subtreeGroupCount": 1,
    "id": 2,
    "parent": 1,
    "version": {
        "rowVersion": 1305203
    }
},
{
    "comment": "",
    "group": {
        "definition": {
            "groupId": 80,
            "groupName": "Account Executives"
        },
        "isPasswordExpiryEnabled": false
    },
    "name": "Account Executives",
    "passwordExpiryEnabled": false,
    "type": "Group",
    "subtreeGroupCount": 1,
    "id": 80,
    "parent": 1,
    "version": {
        "rowVersion": 1305204
    }
},

Enabling Portal Access groups

In Varicent Incentives , you can use the REST API to enable a Portal Access group.

  • Make the following request:

    POST /api/v1/portalaccessgroups/{PortalAccessGroupId}/webusers

    with the password that you want to give to the group of payees contained in the request body:

    Note

    The request body must be in JSON format.

    {
"password":"<password>"
}

    For example,

    curl -X POST -H "Authorization: Bearer API_KEY" 
-H "Model: YOUR_CLIENT_MODEL” 
-H "Content-Type: application/json" 
https://YOUR_ICM10_API_SERVER_ADDRESS/api/v1/portalaccessgroups/80/webusers

    Request Body:

    {
"password":"s3cret!@#$"
}

Updating web users' information

In Varicent Incentives , you can use the REST API to update the following information for a web user: web-enabled status, locked status, change the password on next login status, and passwords.

  • Make the following request:

    POST /api/v1/webusers

    with the data you want to update contained in the request body:

    Note

    The request body must be in JSON format.

    [
{"isWebEnabled":<true/false>,
"isLocked":<true/false>,
"changePasswordOnNextLogin":<true/false>,
"title":"<title>",
"email":"<email address>",
"phone":"<phone number>",
"reportsTo":"<title of user that the payee reports to>",
"name":"<name>",
"id":"<payeeID>",
"password":"<password>"}
]

    For example,

    curl -X POST -H "Authorization: Bearer API_KEY" 
-H "Model: YOUR_CLIENT_MODEL” 
-H "Content-Type: application/json" 
https://YOUR_ICM10_API_SERVER_ADDRESS/api/v1/webusers

    Request Body:

    [
{"isWebEnabled":true,
"isLocked":false,
"changePasswordOnNextLogin":true,
"title":"Vice President Sales",
"email":"kdawson@rti.com",
"phone":"",
"reportsTo":"CEO",
"name":"Kim Dawson",
"id":"VP001",
"password":"S3cret!@#$"}
]