7 Users and Organization Structure RESTFUL Interface

This document provide the information on how to get users and organizational structures list. RESTFul API document explanations.

1 Explanation

  • The submitted parameters are in the data format of key-value pairs (application/x-www-form-urlencoded), and web browsers will package this data and populate into the http body.

  • Authentication Method (/hrm/websevice/hrm_webservice_config.jsp will provide authentication methods configurations)

    • IP Address: Allow to configure multiple client IP in /WEB-INF/prop/HrmWebserviceIP.properties, separate by comma.

    • Token Authentications: Extra parameter in submitted parameters

NameTypeMandatoryDescription

token

string

Yes

json string, each token has 5 minutes validity period (the request-side time and the server-side time principle are consistent), suggest to generate new token for every request.

  • Example:

{
	"key":"92B4BF9322C110E225683F048013B699", //Token+Timestamp milliseconds, then use MD5/SM3 to encrypt to generate as key
	"ts":"1603600893041" // Timestamp milliseconds.
}

  • key generate methods, java sample:

public static void main(String[] args) throws Exception{
	String key = "5936562a-d47c-4a29-9b74-b310e6c971b7" ; //retrieve index method, please browse /hrm/websevice/hrm_webservice_config.jsp
	long l = System.currentTimeMillis() ; // Timestamp milliseconds
	String code = key.concat(Long.toString(l)) ;
	String md5key = Util.getEncrypt(code).toUpperCase() ; //MD5 Encryption and change to UPPERCASE
	Map<String,String> map = new HashMap<>() ;
	map.put("key",md5key) ;
	map.put("ts",Long.toString(l)) ;
	System.out.println(JSONObject.toJSONString(map)); //Token string
}

  • Sample: There are two methods to configure the token, select either one

    • Token Method 1: Use the header method, insert key, ts parameters.

    • Token Method 2: Insert the parameters in the body:

2 Get Divisions List

Request URL

  • /api/hrm/resful/getHrmsubcompanyWithPage

Request Method:

  • POST

Parameters:

NameTypeMandatoryDescription

params

string

Yes

json format data

  • Request Parameter - Sample:

NameTypeMandatoryDescription

subcompanyname

string

Division Name

subcompanycode

string

Division Code

modified

string

modified timestamp; (use >=)

canceled

string

Inactive Data indicator; Default will get active data list. 1: Inactive

custom_data

string

Specify user-defined field data list, multiple comma to be used to separate fields. Please refer to System Backend-Dashboard - Organization Authorization - User-Defined Item - Division Field Define. eg. : divisiondesc

id

string

Division id in OA Database

pagesize

int

Number of records per page, default is 20.

curpage

int

Current page, default is 1

Exnample:

{
	"subcompanyname":"Div001",
	"subcompanycode":"code1",
	"modified":"2020-11-08 00:00:00",
	"created":"2020-11-08 00:00:00",
	"canceled":"",
	"custom_data":"field1,field2",
	"id":"10",
	"pagesize":20,
	"curpage":1
}

jsReturn Sample:

{
	"code": "1", // 1: Successful, others: Failed
	"data": {
		"totalSize": 1, // Page - Total Page Number
		"dataList": [ // Data Set
			{
				"subcompanydesc": "CAL", // Division Name
				"canceled": "", // Inactive indicator，1: Inactive，Others: Non-inactive
				"subcompanycode": "", // Divison Code
				"supsubcomid": "0", // Parent Division ID, 0 or blank means no parent division
				"created": "2020-01-13 17:59:28", // Creation Timestamp
				"modified": "2020-09-06 00:11:00", // Modified Timestamp
				"id": "11", // Division ID, unique ID
				"subcompanyname": "CAL", // Division Abbreviation
				"url": "", // Abandoned field
				"custom_data" : { // User defined data
                    "divisiondesc": "Manage IT Relevant" // User defined data
                },
				"showorder": "0.0" // Display order
			}
		],
	"pageSize": 20, // Split Page - Records per page
	"page": 1 // Split Page - Current Page No. 
	}
}

3 Get Departments List

Request URL:

  • /api/hrm/resful/getHrmdepartmentWithPage

Request Method:

  • POST

Parameters:

NameTypeMandatoryDescription

params

string

Yes

json format data

  • json Parameters Explanation:

NameTypeMandatoryDescription

created

string

Created Timestamp; (use >=)

modified

string

Modified Timestamp; (use >=)

departmentcode

string

Department Code

departmentname

string

Department Name

subcompanyid1

string

Division ID

canceled

string

Inactive Indicator; Default query active data, 1: Inactive

id

string

Department ID in OA Database

pagesize

int

Page Size, number of records per page, default: 20

curpage

int

Current Page, default: 1

custom_data

string

Value can be retrieved from the Department user defined field in OA system. Sample : custom_data: 'field1, field2, field3'

Sample

{
	"departmentname":"Technical",
	"departmentcode":"code1",
	"pagesize":20,
	"curpage":1
}

Return Sample:

{
	"code": "1", // 1: Succeeded, Others: Failed
	"data": {
	"totalSize": 1, // Total Page Number
	"dataList": [ // Data Set
		{
			"canceled": "", // Inactive Indicator, 1: Inactive, others: Non Inactive
			"supdepid": "0", // Parent Department ID
			"departmentmark": "Technical", // Department Abbreviation
			"departmentname": "Techincal Support", // Department Full Name
			"created": "2019-08-28 10:44:12", // Created Timestamp
			"departmentcode": "", // Department Code
			"modified": "2020-09-07 19:40:09", // Modified Timestamp
			"id": "2", // Department id
			"subcompanyid1": "5", // Division id
			"custom_data": { // User-defined data
				"xlk": "Used" //
			},
			"showorder": "0.0" // 
		}
	],
	"pageSize": 20, // Split Page: Number of records per page
	"page": 1 // Split Page: Current Page Number
	}
}

4 Get Positions List

Request URL:

  • /api/hrm/resful/getJobtitleInfoWithPage

Request Method:

  • POST

Parameters:

NameTypeMandatoryDescription

params

string

Yes

json format data

json Parameters Explanation:

NameTypeMandatoryDescription

created

string

Created Timestamp; (use >=)

modified

string

Modified Timestamp; (use >=)

id

string

Position ID in OA Database

jobtitlename

string

Position Name

pagesize

int

Page Size, number of records per page, default: 20

curpage

int

Current Page, default: 1

Sample

{
	"jobtitlename":"Manager",
	"pagesize":20,
	"curpage":1
}

Return Sample:

{
	"code": "1", // 1: Succeeded, Others: Failed
	"data": {
	"totalSize": 1, // Split Page - Page Number
	"dataList": [ // Data Set
		{
			"jobdoc": "", // Relevant Doc id
			"jobtitleremark": "", // Remarks
			"jobresponsibility": "", // Job responsibilities
			"jobtitlename": "Default", // Full Name
			"jobcompetency": "", // Job Requirement
			"created": "2019-03-07 13:12:47", // Created Timestamp
			"modified": "2019-03-07 13:12:47", // Modified Timestamp
			"id": "1", // Position ID
			"jobtitlemark": "Default", // Abbreviation
			"jobdepartmentid": "" // Department id (Abandoned Field)
		}
	],
	"pageSize": 20, // Split Page - Number of records per page
	"page": 1 // Split Page - Current Page number
	}
}

5 Get Users List

Request URL:

  • /api/hrm/resful/getHrmUserInfoWithPage

Request Method:

  • POST

Parameters:

NameTypeMandatoryDescription

params

string

Yes

json format data

json Parameters Explanation:

NameTypeMandatoryDescription

created

string

Created Timestamp; (use >=)

modified

string

Modified Timestamp; (use >=)

workcode

string

Employee Code

subcompanyid1

string

Division ID

departmentid

string

Department ID

jobtitleid

string

Position ID

id

string

User ID in OA Database, PK

loginid

string

User Login ID

base_custom_data

int

To get OA User defined field: [Organization Authorisation] - [User-Defined Settings] - [Staff card fields] - Basic Info. Sample: base_custom_data: 'field1, field2, field3'

person_custom_data

string

Same as above base_custom_data (Personal Information)

work_custom_data

string

Same as above base_custom_data (Work Information)

pagesize

int

Records per page, default: 20

curpage

int

Current page number, default: 1

Sample

{
	"workcode":"S001"
}

Return Sample:

{
    "code": "1", //1: Succeeded, Others: Failed
    "data": {
        "totalSize": 1, //Total Records returned
        "dataList": [ //Data list
            {
                "companystartdate": "2020-11-01",//Date Joined
                "tempresidentnumber": "",
                "createdate": "2020-12-08", //Creation Date
                "language": "", //Default User Language
                "workstartdate": "", 
                "subcompanyid1": "5",//Division ID
                "subcompanyname": "Singapore", //Division Name
                "joblevel": "0", //Job level: From 0 - 9
                "startdate": "",
                "password": "xxxx",
                "subcompanycode": "", //Division Code
                "jobactivitydesc": "",//Job Description
                "bememberdate": "",//Only used in China
                "modified": "2021-03-04 21:42:03",//Modified Date
                "id": "30",//User ID in OA Database, Unique ID
                "mobilecall": "",//Other Mobile Number
                "nativeplace": "", //Nationality
                "certificatenum": "", //Certificate Number
                "height": "", //Height
                "loginid": "joseph", //Login ID
                "created": "2020-12-08 02:16:35", //Created Date Time
                "degree": "", //Degree Holder description
                "bepartydate": "", //Only used in China
                "weight": "2147483647", //Weight
                "telephone": "",//Telephone Number
                "residentplace": "",//Resident Place
                "lastname": "Joseph, Low", //Employee Name
                "healthinfo": "0", 
                "enddate": "",
                "maritalstatus": "未婚", //Marital Status
                "departmentname": "CEO Office", //Department Name
                "folk": "",
                "status": "1", //Employee Status: 0: Probabtion, 1: Permanent, 2: Temp Staff, 
                //3:Extended Probation 4: Terminated 5: Resigned 6: Retired 7: Invalid
                "birthday": "", 
                "accounttype": "0", //User Account Type: Null: Main Account 1: Sub-account
                "jobcall": "5", //Job Category
                "managerid": "", //Direct Superior User ID in OA Database
                "assistantid": "", // Assistant User ID in OA Database
                "departmentcode": "", //Department Code
                "belongto": "",
                "email": "kenyu.low@weaver.com.sg", //User Email Address
                "seclevel": "100", //User Security Level
                "policy": "",
                "jobtitle": "3", // Position ID in OA Database
                "workcode": "S001", //Employee ID
                "sex": "男", //Sex
                "departmentid": "8", //Department ID (Departmen Master PK)
                "homeaddress": "",
                "mobile": "",
                "lastmoddate": "2021-03-05", //Last Modified Date
                "educationlevel": "0", 
                "islabouunion": "0", //Only used in China
                "locationid": "3", //Work location ID
                "regresidentplace": "",
                "dsporder": "30.0" //Display Order in OA
            }
        ],
        "pageSize": 20,
        "page": 1
    }
}

6 Sync Division

Explanation: During the synchronization, if the data requested does not exist in OA, the record will be created automatically.

Request URL:

  • /api/hrm/resful/synSubcompany

Request Method:

  • POST

Parameters:

NameTypeMandatoryDescription

data

string

Sync Data set, json format data

Sample

[
    {
        "@action":"add", //add: Insert New, edit: Update
        "code":"D001",
        "shortname": "Div001",
        "fullname": "Div001",
        "parentcode":"",
        "canceled": "",
        "order":"9",
        
    }
]

Return Sample:

{
    "result": {
        "D001": {
            "msg": "插入成功", //Actions successfully
            "code": "1"
        }
    },
    "code": "1"
}

7 Sync Department

Explanation: During the synchronization, if the data requested does not exist in OA, the record will be created in OA automatically.

Request URL:

  • /api/hrm/resful/synDepartment

Request Method:

  • POST

Parameters:

NameTypeMandatoryDescription

data

string

Sync Data set, json format data

Sample

[
    {
        "@action":"add", //add: Insert New, edit: Update, delete: Update "canceled" field value
        "code":"Dep001", //Department Code
        "shortname": "Dep001", //Department Short Name
        "fullname": "Dep001",//Department Full Name
        "org_code":"D001",//Division Code
        "parent_code":"", //Parent Department Code
        "canceled": "", //This field will be used when @action: delete
        "order":"9", //Display Order in OA
        
    }
]

Return Sample:

{
    "result": {
        "Dep001": {
            "msg": "插入成功",
            "code": "1"
        }
    },
    "code": "1"
}

8 Sync Positions

Explanation: During the synchronization, if the data requested does not exist in OA, the record will be created automatically.

Request URL:

  • /api/hrm/resful/synJobtitle

Request Method:

  • POST

Parameters:

NameTypeMandatoryDescription

data

string

Sync Data set, json format data

Sample

[
    {
        "@action":"add", //add: Insert New, edit: Update
        "jobtitlecode":"JOB0001",
        "jobtitlename": "Technician",
        "jobtitleremark": "Technician",
    }
]

Return Sample:

{
    "result": {
        "JOB0001": { //Job Code
            "msg": "操作成功", //Action Successful
            "code": "1" //1: Succeeded, Others: Failed
        }
    },
    "code": "1"
}

9 Sync Users

Explanation: During the synchronization, if the data requested does not exist in OA, the record will be created automatically.

For this interface, validation is against to the workcode, if the workcode exists in the OA system, the interface will take it as update function, if the workcode does not exist in OA, will insert as a new employee.

Request URL:

  • /api/hrm/resful/synHrmresource

Request Method:

  • POST

Parameters:

NameTypeMandatoryDescription

data

string

Sync Data set, json format data

Sample

[
    {
        "workcode":"S001a",
        "subcompany":"D001", //User's Division, 2 methods: 1) Full division path (HQ>Div>SubDiv), but side effect is the full path exists in OA system, it will update user's Division, else it will insert the division as new division. 2) Use {JSON}{"subcompanycode":"Div001"} as a string for this value, specify division code. (will not create new division)
        "department":"Dep001", //User's Department, 2 methods: 1) Full department path (Dep001>SDep001), side effect: If the full path exists in OA system, it will update user's Department; else it will insert the division as new department. 2) Use {JSON}{"departmentcode":"SDep001"} as a string value, specify department code. (will not create new division)
        "lastname":"Alexandra",//Employee Name
        "loginid":"alex",
        "password":"weaver2020", //Plain text, will be encrypted after
        "seclevel":"80",//Security Level 0-100
        "sex":"Male",//
        "jobtitle":"Technical Engineer", //User's Position, 2 methods: 1) Position Name, side effect: If the position name does not exist in OA, it will insert as new position. 2) Use {JSON}{"jobtitlecode":"fw"} as a string value, specify department code. (will not create new division)
        "jobactivityid":"Executive", //If jobtitle uses JSON can skip this field
        "jobgroupid":"Executive", // Job Type Group ID, if jobtitle uses JSON can skip field
        "jobcall":"2",//Job name, data linked to HrmJobCall Table
        "joblevel":"0", //Job Level Integer Value Only
        "jobactivitydesc":"Description of Job", //Description of Job
        "managerid":"S001", //Important field: Direct Superior, only support user's workcode field
        "assistantid":"",//User's Assistant, only support user's workcode
        "status":"0",//Employee Status: 0: Probabtion, 1: Permanent, 2: Temp Staff, 
                //3:Extended Probation 4: Terminated 5: Resigned 6: Retired 7: Invalid
        "locationid":"", //Work Location
        "workroom":"", //Office room name
        "telephone":"+6512345675", //Telephone number
        "mobile":"+6512345675", //Mobile Number
        "mobilecall":"+6512345675", //Other mobile number
        "fax":"",//Fax number
        "email":"sales@weaver.com.sg", //Important Field, if OA requires email notifications
        "systemlanguage":"English", //User System Language
        "birthday":"2020-01-01", //Birthday, Format: yyyy-MM-dd
		"folk":"", //Ethnic Group
        "nativeplace":"", //Hometown
        "regresidentplace":"", //Used in China Only
        "certificatenum":"", //ID Number, must be unique
        "maritalstatus":"Married",
		"accounttype":"", //主账号：Main Account | 次账号：Sub Account
        "belongto":"",//Main Account, effective only if accounttype:次账号, only support workcode
        "companystartdate":"2021-03-01",  //Date Joined the company, Format: yyyy-MM-dd
        "workstartdate":"2021-03-15", //Date started to work, Format: yyyy-MM-dd
        "base_custom_data":{
            "field01":"test"
        }, //Fields from [Organization Authorisation]-[User-defined Setting]-[Staff Card fields] - [Basic Info] fields
        "person_custom_data":{
            "field01":"test01",
            "field02":"test003"
        },//Fields from [Organization Authorisation]-[User-defined Setting]-[Staff Card fields] - [Personal Information] fields
        "work_custom_data":{
            "field03":""
        },//Fields from [Organization Authorisation]-[User-defined Setting]-[Staff Card fields] - [Working Experience] fields
    }
]

Return Sample:

{
    "result": {
        "S001b": {
            "msg": "S001b|Jason|创建|成功|", 
            "code": "1" //1: Succeeded, Others: Failed
        }
    },
    "code": "1"
}
Previous6 SSO non-intrusive development example

Last updated