HR Integration Instructions
Introduction
This document provides details and instructions on how to use the CMO Compliance HR Integration Web Services for importing and updating user details in the User Module.
Click the PDF Icon in the top right corner of this page to download a PDF version of this guide.
Web Services Details
The CMO HR Integration Web service is a uni-directional integration, allowing you to pass HR system data to CMO. This will allow you to integrate your existing HR system with your CMO environment to ensure user data integrity between the two systems.
CMO’s web services can be called over the web using the Simple Object Access Protocol (SOAP), and data is passed via the web service call in the form of standard XML schemas. The service will then either import or update the user details in the target CMO environment.
Access to the Web Service itself is provided at the following URLs:
| Staging | https://{clientname}-staging.cmo-compliance.com/webservice/ HRImport.asmx |
| Production | https://{clientname}.cmo-compliance.com/webservice/ HRImport.asmx |
The Web Service WSDL is available by appending ?WSDL to the end of the URLs above. The WSDL can be used to link to the service definition in SOAP tools such as SoapUI, or within custom SOAP methods for most programming languages and web service integration tools.
The specific web service required from the URL above is titled UserImport. This web service will allow you to pass user data directly to CMO. It requires you to pass a valid CMO username and password when calling it (passed in the <web:login> and
<web:password> fields of the SOAP call, respectively), followed by the user data payload in an XML format. The schema for the XML data is provided in section 5 below, and an example SOAP call is provided in section 8 below.
Fields to integrate
Please select which of the following fields you would like to pass from your HR system to CMO COMPLIANCE. Shaded fields are mandatory
Please note, if you need to automate the assignment of a user against Roles, User Groups, Org Units and Entities in CMO, you will need to add additional info fields to your HR system, to represent the CMO Roles, User Groups, Org Units and Entities that users can be assigned to. These details need to be passed in the web service call to automate user assignments in the call. The other option is to pass users to the CMO environment without these assignments (i.e. with just their HR details), and then manually edit the users in CMO to assign them to Roles, User Groups, Org Units and Entities.
| Field Name | Description | Include? |
| FirstName | The User's first name | Yes |
| LastName | The User's last name | Yes |
| LoginName | The User’s login name. Used as a primary identifier for matching to existing records. | Yes |
| Password | The User's password | |
| The Users' email address | ||
| UserRole | The User’s Role in CMO. Value passed must match to an existing CMO Role in your CMO environment. If not passed, no role is assigned, and user will not have access to any functionality in the application. | Yes |
| JobTitle | The User's job title | |
| Classification | The user's classification (employee or contractor) | |
| Phone | The user's telephone number | |
| Mobile | The user's mobile/cell number | |
| EmailReminders | Determines whether the user should receive email reminders from the CMO application. Value should be ‘Yes’ or ‘No’ | |
| ManagerLoginName | The login name of the user’s direct superior/ manager. Managers are utilised in CMO as escalation points for overdue items assigned to the user. Note that the value passed in this field must be the manager’s login name in CMO. Multiple manager login names can be passed in the same field, separated by commas (,) |
|
| UserGroup | User Groups in CMO to assign the user to. The value passed must match to an existing CMO user group in your environment. Multiple user groups can be passed in the same field, separated by commas (,) | |
| IsADUser | If AD (Active Directory) Integration is active for single sign on, you can set this user to be an AD user in CMO for single sign-on purposes, by passing the value ‘Yes’ in this field | |
| ADUserObjectID | If the user is an AD user in CMO, you can pass their ADUserObjectID to help with matching them to their AD account | |
| DeactivationStart | The user’s start date for their deactivation period. Generally used if a user goes on leave or exits from the company | |
| DeactivationEnd | The user’s end date for their deactivation period. If no end date is passed, the user is deactivated indefinitely, until a deactivation end date is set for them. | |
| Assignments | If you need to pass individual user assignments for organisational units and/or entities, then they can be done by passing the assignment details in a separate block of data from the UserGroup field. Note that any assignment details passed will be added to the user’s assignments in additional to any assignments applied via their UserGroup associations. | |
| OrgUnit | Part of an <Assignment> block – this field needs to match to an existing CMO OrgUnit to assign the user to it (with the specific role passed in the <Assignment> block) | |
| Entity | Part of an <Assignment> block – this field needs to match to an existing CMO Entity to assign the user to it (with the specific role passed in the <Assignment> block) |
If you require additional user info fields (which cannot be mapped to any of the fields above) for your HR integration, please ensure they are listed in the table below, along with their field types. These additional info fields will be set up in CMO as well, as part of your standard solution configuration:
| Field Name | Field Type |
| Lorium Ipsum | Lorium Ipsum |
XML Schema
The generic XML schema for passing User, Org Unit, and Entity data is provided in the sections below, and will be sent to you in a .xsd file. This schema will be updated based on the fields you specify in section 4 above:
Schema for Users
The generic XML schema for passing Users data is provided below:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:web="http://cmoglobal/WebServices/">
<soapenv:Header/>
<soapenv:Body>
<web:AsyncUsersImport>
<!--Optional:-->
<web:login>UserName</web:login>
<!--Optional:-->
<web:password>Password</web:password>
<!--Optional:-->
<web:xmlData>
<Users xmlns="">
<User>
<FirstName>Test User First Name</FirstName>
<LastName>Test User Last Name</LastName>
<LoginName>LoginName</LoginName>
<Password>Password</Password>
<Email>EmailAdress</Email>
<JobTitle>Employee Title</JobTitle>
<EmailReminders>YesOrNo</EmailReminders>
<MobileAccess>YesOrNo</MobileAccess>
<UserRole>RoleName</UserRole>
<Assignments>
<Assignment>
<OrgUnit>Org Unit Name</OrgUnit>
<Entity>Entity Name</Entity>
<UserRole>RoleName</UserRole>
</Assignment>
</Assignments>
</User>
</Users>
</web:xmlData>
</web:AsyncUsersImport>
</soapenv:Body>
</soapenv:Envelope>
Notes about the User Schema
- Within the <Users> tags, you can have as many individual <User> blocks of data as required. This will allow multiple users to be passed in a single web service call, broken up into separate <User> blocks, and will save you having to call the web service every time you need to pass an individual user record.
- Within each <User> block, there is a block of <Assignments> tags. This allows for as many individual <assignment> blocks to be passed for each user, to allow individual role, org unit and entity assignments to be passed if required. Note that this will work in conjunction with the data passed in the <UserGroup> tag. Any data passed in the <UserGroup> and <Assignment> tags, will form a union of assignments for the user in CMO
- CMO allows you to integrate as many additional info fields as required, if any need to be part of the HR integration. These must first be set up in CMO as additional info fields in the Users module, and CMO will then map the additional info fields to XML schema fields. An updated XML schema will be provided to you, with additional field names, if any changes are required to accommodate such fields. Additional info fields are to be specified in section 6 of this document.
- Note that only <LoginName> is required to be passed to identify an existing user in CMO. All other fields are optional when updating an existing user in CMO. This means that, if a field is not passed in the XML data for an existing user, that field’s value in CMO will not be modified (unless otherwise specified in section 6 below)
Schema for Org Units
The generic XML schema for passing Org Unit data is provided below:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:web="http://cmoglobal/WebServices/">
<soapenv:Header/>
<soapenv:Body>
<web:AsyncGroupsImport>
<!--Optional:-->
<web:login>UserName</web:login>
<!--Optional:-->
<web:password>Password</web:password>
<!--Optional:-->
<web:xmlData>
<OrgUnits xmlns="">
<OrgUnit>
<OrgType>OrgTypeName</OrgType>
<OrgParentName>ParentOrgUnit</OrgParentName>
<OrgName>OrgName</OrgName>
<ManagerName></ManagerName>
<ManagerEmail></ManagerEmail>
<ManagerPhone></ManagerPhone>
<Country></Country>
<State></State>
<City></City>
<StreetAddress></StreetAddress>
<PostCode></PostCode>
<Phone></Phone>
<Fax></Fax>
</OrgUnit>
</OrgUnits>
</web:xmlData>
</web:AsyncGroupsImport>
</soapenv:Body>
</soapenv:Envelope>
Schema for Entities
The generic XML schema for passing Entity data is provided below:
<xsd:schema elementFormDefault="qualified" version="1.0">
<xsd:element name="CmoAuditeeFeed">
<xsd:complexType>
<xsd:sequence minOccurs="0" maxOccurs="1">
<xsd:element ref="Entities"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="Entities">
<xsd:complexType>
<xsd:sequence minOccurs="0" maxOccurs="unbounded">
<xsd:element ref="Entity"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="Entity">
<xsd:complexType>
<xsd:all minOccurs="0" maxOccurs="1">
<xsd:element minOccurs="1" maxOccurs="1" ref="EntityName"/>
<xsd:element minOccurs="0" maxOccurs="1" ref="EntityType"/>
<xsd:element minOccurs="0" maxOccurs="1" ref="OrgUnit"/>
<xsd:element minOccurs="0" maxOccurs="1" ref="City"/>
<xsd:element minOccurs="0" maxOccurs="1" ref="Country"/>
<xsd:element minOccurs="0" maxOccurs="1" ref="State"/>
<xsd:element minOccurs="0" maxOccurs="1" ref="Street"/>
<xsd:element minOccurs="0" maxOccurs="1" ref="PostCode"/>
<xsd:element minOccurs="0" maxOccurs="1" ref="Description"/>
<xsd:element minOccurs="0" maxOccurs="1" ref="ActiveStatus"/>
<xsd:element minOccurs="0" maxOccurs="1" ref="Contact"/>
<xsd:element minOccurs="0" maxOccurs="1" ref="Email"/>
</xsd:all>
</xsd:complexType>
</xsd:element>
<xsd:element name="EntityName" type="xsd:string"/>
<xsd:element name="EntityType" type="xsd:string"/>
<xsd:element name="OrgUnit" type="xsd:string"/>
<xsd:element name="City" type="xsd:string"/>
<xsd:element name="Country" type="xsd:string"/>
<xsd:element name="State" type="xsd:string"/>
<xsd:element name="Street" type="xsd:string"/>
<xsd:element name="PostCode" type="xsd:string"/>
<xsd:element name="Description" type="xsd:string"/>
<xsd:element name="ActiveStatus" type="xsd:string"/>
<xsd:element name="Contact" type="xsd:string"/>
<xsd:element name="Email" type="xsd:string"/>
</xsd:schema>
Integration Logic
There are some additional pieces of integration logic which will need to be decided on before the integration can be finalised. Please add your answer for each question below, to the third column, by using one of the bold text options in the second column, as the response:
| Full User List Logic | Will you be passing your entire user list with each call of the web service, or will you only be passing updated user data with each call? |
| User Assignment Logic | Will you be passing only new user assignments with each web service call, or will you require the user’s assignment’s to be fully redefined with each web service call? |
| User Manager Logic | Do you require a user’s manager list in CMO to be appended to with any new managers in each call, or will you be passing their full current manager list with each call? |
| User Deactivation Logic | When calling the web service, if a user is not passed in the xml data, do you require them to be deactivated or can they be left unchanged? |
Call the API
Setup
API uses the token authorization (JWT). To enable JWT for application add next lines to the web.config file (:
<!-- Enable JWT for the app -->
<add key ="Authentication.Jwt.Enabled" value="true" />
<!-- Secret key to encode tokens (required) -->
<add key ="Authentication.Jwt.Secret" value="" />
<!-- Token expiration time (minutes) -->
<add key ="Authentication.Jwt.Expire" value="20" />
Ensure that "Secret" is not empty. You can use attached tool to generate keys or use any randomly generated key.
Do not share keys between environments. Every environment should have own key.
Only users with next permissions can fetch the data: "Allow Edit Users", "Allow Edit User Assignments".
Usage
- Obtain token - POST/api/token
{
login:userLogin,
password: userpassword
}
- Add authorization header to the request with received token.
Authorization:Bearer
eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWJqZWN0IjoyLCJleHAiOjE0OTU3OTU xNzguMH0.6FbTQeg1aWvnPSe3NAnf5EVGWzuDmAgUp37M1NIoJcU
- Make request - GET/api/export/exportusers
Supported Parameters
from — to filter users by the starting date of last modification
to — to filter users by the ending date of last modification
page — current page (default: 1)
perPage — number of records (users) to show per page ( from 1 to 300, default is 100)
Important Note: From and To field must be specified in UTC Time Zone. Supported Format for the From and To fields: yyyy-MM-dd HH:mm:ss
Web Service Response Message
Calling the Web Service will provide a number of response messages.
A successful call of the web service will provide a message in the following format:
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http:// www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<UserControlledImportResponse xmlns="http://cmoglobal/WebServices/">
<UserControlledImportResult>
<UsersImportResults xmlns="">
<UsersImportResult>Partially completed</UsersImportResult>
<Exceptions>
<Exception>-==Start selected user import==-</Exception>
<Exception>Begin Processing user: cmotest</Exception>
<Exception>User: cmotest saved in database.</Exception>
Exception>
<Exception>cmotest roles, groups, superiors, jobs, auditee assignments updated.</
<Exception>Imported: 1 Selected: 1 Total: 1</Exception>
<Exception>-==Users import END ==-</Exception>
<Exception>Users imported: 1</Exception>
</Exceptions>
</UsersImportResults>
</UserControlledImportResult>
</UserControlledImportResponse>
</soap:Body>
</soap:Envelope>
This informs you that the import has been successful (or partially successful), and informs you of the number of users that have been imported. The size of this message will grow and shrink in size depending on the amount of individual user records passed in the XML data.
Erroneous messages will take on the format of exception messages such as this one, which will alert you that the Import has failed, due to you passing incorrect user credentials during the SOAP call:
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http:// www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<UserControlledImportResponse xmlns="http://cmoglobal/WebServices/">
<UserControlledImportResult>
<UsersImportResults xmlns="">
<UsersImportResult>False</UsersImportResult>
<Exceptions>
<Exception>Login or password is incorrect.</Exception>
</Exceptions>
</UsersImportResults>
</UserControlledImportResult>
</UserControlledImportResponse>
</soap:Body>
</soap:Envelope>
Erroneous messages include the following:
- Incorrect username/password for webservice call authentication
- Org Unit or Entity not found
- Data in incorrect format (i.e. date fields)
- First Name/ LastName field missing
Note that no error message is shown if a login name does not match an existing login name in CMO COMPLIANCE. The webservice will automatically create a new user with the details provided in such an instance.
Please note that all date fields must be in the format DD.MM.YYYY or they will not be able to be processed correctly.
All exceptions are logged in a separate log file on the CMO web server, so please alert CMO Support of any errors you encounter during a web service call, providing the date and time the call was made, your full web service call, and the XML data, so that CMO can inspect the logs and determine whether the issue is a data/formatting issue, or an issue with the integration.
Example Web Service Call
Below is an example web service call to your CMO environment, using SoapUI (SoapUI is a free software tool that provides access to test SOAP web service calls. It can be downloaded from http://sourceforge.net/projects/soapui/ ):
The below SOAP call will pass data for a single user in CMO with the login JSmith
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:web="http://cmoglobal/WebServices/">
<soapenv:Header/>
<soapenv:Body>
<web:UserControlledImport>
<web:login>cmoadmin</web:login>
<web:password>cmoadmin15!</web:password>
<web:xmlData>
<CmoUserFeed xmlns="http://schemas.xmlsoap.org/soap/encoding/">
<Users>
<User>
<FirstName>John </FirstName>
<LastName>Smith</LastName>
<LoginName>JSmith</LoginName>
<Password>jsmith15!</Password>
<Email>Support@cmo-compliance.com</Email>
<UserRole>Super User</UserRole>
<JobTitle>Administration Assistant</JobTitle>
<Classification>Employee</Classification>
<ADLogin>TestADUser</ADLogin>
<Phone>0395217077</Phone>
<Mobile>0477710068</Mobile>
<EmailReminders>True</EmailReminders>
<ManagerLoginName></ManagerLoginName>
<UserGroup>Administrators</UserGroup>
<IsADUser>True</IsADUser>
<ADUserObjectID>4CADA701-616F-4BE3-A4B1-
78944411B6F5</ADUserObjectID>
<DeactivationStart>15.03.2015</DeactivationStart>
<Assignments>
<Assignment>
<UserRole>Super User</UserRole>
<OrgUnit>QLD</OrgUnit>
<Entity>Western Village</Entity>
</Assignment>
</Assignments>
</User>
</Users>
</CmoUserFeed>
</web:xmlData>
</web:UserControlledImport>
</soapenv:Body>
</soapenv:Envelope>
Automation of Web Service Calls
If you require automation of the web service calls, you will need to consult your current HR system’s help guide to determine what functions are available for you to call SOAP web services, and what options you have for scheduling these to be called automatically. If there is no built-in scheduling option, you may be able to automate the calling of these functions by scripting them via a windows batch file, and setting the file to run via the Windows Task Scheduler, or a Windows Service.
CMO can assist you with setting up such automation solutions as an additional service if required.