Contact & Company Import Tool
The Contact & Company Import Tool (accessed via the 'Import Contacts & Companies' menu option within the Eploy Core System) can be used to import company structure, contact records and associated users into Eploy. It can also be used to update existing records. If you plan to use the API to synchronize contact and company data, the tool can also be used to check the format of your data and diagnose any issues that could result in errors.
Import Formats
The import tool supports two file formats, CSV and XML. Refer to the ‘Sample Data’ section for examples.
Import Types
The import tool now has three modes for importing data. These are Eploy ID, External ID and Standard.
Eploy ID
Requires that the records being imported have their Eploy ID specified, I.e. CompanyID for Companies and ContactID for Contacts. Because of this constraint, no new records can be imported using this method, we only allow the updating of existing records.
External ID
Requires that the records being imported have their External ID specified, I.e. ImportID for Companies and Contacts. Existing records will be matched on that value and records that do not match will be inserted.
Standard
This import is the one that existed in version 38. It works by matching based on Company Name or other Matching Options. This can be used to create companies and contacts and even users. This can also be used to update External IDs.
Required / Allowed Fields
For each type of Import, Eploy ID, External ID and Standard there are certain fields that are required and others that are not allowed altogether.
Eploy ID
- Required
- CompanyID / ContactID - Main RecordID
External ID
- Required
- ImportID
- Not Allowed
- CompanyID / ContactID - Main RecordID
Standard
- Required
- CompanyName
- Not Allowed
- CompanyID / ContactID - Main RecordID
If you include the ImportID field on an Eploy ID or Standard Import then that column will be updated as it is not used for matching existing records in those import types.
Including the CompanyName field in any Import other than Standard will also result in the Company Name being updated.
We have 3 fields for ParentIDs, ParentCompanyID, ParentImportID and ParentCompanyName. Only one of these can be passed for each Companies and Contacts. We will give a validation error on the first page, where we tell users they are using the wrong fields for the type of import chosen.
Validation Checks
Standard
There is no data validation so this will just validate columns on first page.
Eploy ID
If Company ID column exists then ALL of them must be in Eploy.
If Contact ID column exists, then ALL of them must be in Eploy.
If there is a Parent Company ID or Parent Contact ID that do not exist in Eploy, these give errors as well.
External ID
Company Import ID's must be populated for each row and must be unique for each company. It can appear multiple times against the different Contacts, but all the Company Fields must be the same.
If there is a Parent External Company ID that do not exist in Eploy these will only get set if the parent company is included in the import.
N.B. Some of these may still not get set as the External ID passed is not even in the DB or Import Sheet. These will just not get set in the DB.
Contact Import ID's are populated for each row and must be unique for each contact. It can appear multiple times against the different Users (As a contact can have multiple Users of different types), but all the Contact Fields must be the same.
If there is a Parent External Contact ID that do not exist in Eploy these will only get set if the parent company is included in the import.
N.B. Some of these may still not get set as the External ID passed is not even in the DB or Import Sheet. These will just not get set in the DB.
All
User Field Checks
If we are going to create any users for any of these contacts, we need the minimum number of fields:
- UserDisplayName
- Username
- UserTypeID
It is also recommended that you include Usr_Copy_Usr_ID to copy the permissions granted from another existing user on Eploy. This is not a required field, but without specifying it the user record will have no permissions and the user will be unable to log in until a system administrator manually allocates permissions to them.
User Business Logic Checks
If we are going to insert or update any users from these contacts, we do not allow the creating of users with duplicate Usernames, this includes Users that are archived, they still get included in the checks as they could be re-activated at a later date, creating invalid data if not checked upon import.
Also UserEmails must be unique for core system users. We will not set this for HM users. If there is data in the UserEmail column and the UserType is not 1 (Core System User) then we will not set this field.
Passwords
Passwords cannot be set during the import, forgotten password links can be sent out for new Users.
Sample Data
Below are sample import files, designed to show the columns allowed and the structure of the data source.
CSV
ExternalID Sample.csvXML
Candidate Import Tool
The Candidate Import Tool (accessed via the 'Import Candidatess' menu option within the Eploy Core System) can be used to import a large number of candidates, along with application and placement records (if desired), there is currently no functionality to update existing records, this tool with either import new candidates, or choose to “exclude” records from the import if their e-mail address has already been assigned to an existing candidate.
Import Formats
The import tool supports two file formats, CSV and XML. Refer to the ‘Sample Data’ section for examples.
Import Types
Unlike other imports, there is only a standard import type for the Candidate tool, so this never changes.
Data Restrictions (45 Onwards)
Whether the data is CSV or XML, the final format of the data when imported into Eploy is CSV before it gets inserted into the Database. This means that XML data gets converted to CSV pre-import. Because of this the data sent to the Import API must be valid CSV. We follow the RFC standard for CSV data, which is the same format output by Microsoft Excel.
To this end the following demonstrates the format data needs to be in to be valid.
Normal
Example of valid CSV data, with no special characters.
1Col 1,Col 2,Col 3,Col 4,Col 5 2This is normal,This is normal,This is normal,This is normal,This is normal 3
Above you can see that normal text data does not require double quote encapsulation, although it can use it if desired.
Special Characters
Example of valid CSV data, with no special characters.
1Col 1,Col 2,Col 3,Col 4,Col 5 2This is normal,"This has "" double quote",This has 'single quote,"This has a , comma","This "" has 'quotes and , commas" 3
Above there are double quotes (“
), single quotes ('
) and commas (,
). Double Quotes and Commas are part of the structure of a CSV, so they must be escaped or encapsulated. To escape the double quote you need to precede the value with another double quote and encapsulate the data in double quotes. For single quotes, nothing extra is required. Commas require encapsulation too.
Required / Allowed Fields
Below are the minimum fields required to create a Candidate, and it’s related Applications and Placements. Note there are additional checks depending what’s passed in, this will be covered in the Validation Checks.
-
Required for Candidates Only (not creating applications or placements):
-
Cand_Email
-
-
Required for Applications:
-
VacApp_App_Date
-
VacApp_VacancyID
-
-
Required for Placements:
-
Plcmt_Start_Date
-
In order to Import Applications and Placements, the applicable flag (Create_Application or Create_Placement) must be set 1 (or 'true', or ‘yes’), and the application / placement fields must be present within the import file.
Validation Checks
Candidates:
The validation checks for the Candidate are standard data type checks (i.e. and ensuring the Cand_Email is a valid email address).
If the Create_Application/Create_Placement columns are present, and set to no, the import will fail if any application or placement fields are populated, these fields should be left blank if they aren’t being imported.
Applications:
-
The Create_Application column must be set to 1 (or ‘yes’ or ‘true’)
-
The VacApp_App_Date and VacApp_VacancyID must be set.
-
If the VacApp_ApplicationStage_ID is set, the following criteria must be met:
-
The Workflow ID on the selected vacancy must be same as the Workflow ID on the Application Stage
-
If the VacApp_ApplicationStatus_ID is set, it must be available for the Application Stage (This will change depending on if the Application is at an Application Stage or a Placement Stage)
-
If the Application Stage is an Action Stage, the Status ID must be 0.
-
If the Application Stage is a Placement stage and “Create_Placement” is 0, the status id must be 0 (placement not created).
-
If the Application Stage is a Placement stage and “Create_Placement“ is 1, the status id must be a valid placement status.
-
-
If Create_Application is set to 0 (or ‘no’ or ‘false’) then no other VacApp_ columns should be populated.
Placements:
-
The Create_Placement column must be set to 1 (or ‘yes’ or ‘true’)
-
At least one Placement column must be present when setting Create_Placement to 1.
-
The Plcmt_Start_Date must be filled in, this is the only mandatory field for Placements.
-
The Plcmt_End_Date must be greater than the start date, if this column is set.
-
If the Plcmt_Sal is set, we also need the Plcmt_Hrs_Per_Wk and Plcmt_Sal_Time_Int_ID set as well. This is to double check the salary is correct.
-
If the Create_Placement column is set to 0 (or ‘no’ or ‘false’) no other Plcmt_ columns should be populated.
-
If the VacApp_ApplicationStage_ID is set, it must be a valid Placement Stage.
-
You cannot create a placement without first creating an application.
Sample Data
Below are sample import files, designed to show the columns allowed and the structure of the data source.CSV
XML
Drop Down Lists Import Tool
The Drop Down Lists Import Tool (accessed via the 'Import Drop Down Lists' menu option within the Eploy Core System) can be used to import drop down list entries, which may be used for various fields within the Eploy system. If you plan to use the API to synchronize drop down list data, the tool can also be used to check the format of your data and diagnose any issues that could result in errors.
For drop down lists that support hierachy (e.g. Locations), you can specify the immediate parent of each entry to build/update the hierarchy of the dropdown via the import.
For drop down lists that support archiving, you can specify whether they are active or not. Not specifying an active flag for new records will assume they are active.
Import Formats
The import tool supports two file formats, CSV and XML. Refer to the ‘Sample Data’ section for examples.
Import Types
The import tool now has three modes for importing data. These are Eploy ID, External ID and Standard.
Eploy ID
Requires that the records being imported have their Eploy ID specified. Because of this constraint, no new records can be imported using this method, we only allow the updating of existing records.
External ID
Requires that the records being imported have their External ID specified.s. Existing records will be matched on that value and records that do not match will be inserted.
Standard
Neither the Eploy ID or External ID are required. Existing records will be matched on Description and records that do not match will be inserted.
CSV
XML
API
All types of Import that can be done in the core system using the interface can also be performed using the API, the API is to be used with a SOAP or REST envelope.
Location
All API methods are located under https://{eploycoresystemdomain}/API/Import
{eploysystemdomain} will be the designated domain where your core Eploy system is hosted, e.g. https://abctrading.eploy.net/API
- Company and Contact: https://{eploycoresystemdomain}/API/Import/CompanyContact
- Drop Down: https://{eploycoresystemdomain}/API/Import/DropDownList
Authorisation
We have two methods for authorising API requests, Basic and OAuth.
Basic (Deprecated)
When calling import methods using Basic a header needs to be set called 'Authorization'.
The Authorization header needs be in the following format:
Authorization: Basic <client_id:client_secret>
The client_id:client_secret need to be base64 encoded.
Existing customers with Basic API Keys setup can continue to use them, any customers that setup API Keys from version 42 onwards, will no longer have this option.
OAuth
To use OAuth, call the GetOAuthToken method. This takes no parameters in the request body.
When calling the GetOAuthToken a header needs to be set called 'Authorization'.
The Authorization header needs be in the following format:
Authorization: Basic <client_id:client_secret>
The client_id:client_secret need to be base64 encoded.
Example Header Creation
Client ID: eploy
Client Secret: oabLkRauQkbdHYmZfaYW
Now combine the client id and secret:
eploy:oabLkRauQkbdHYmZfaYW
Now base64 encode this:
ZXBsb3k6b2FiTGtSYXVRa2JkSFltWmZhWVc=
Now build the header:
Authorization: Basic ZXBsb3k6b2FiTGtSYXVRa2JkSFltWmZhWVc=
Example OAuth Token Request
POST /API/Auth/GetOAuthToken HTTP/1.1
Host: abctrading.eploy.net
Content-Type: application/json
Content-Length: length
Authorization: Basic ZXBsb3k6b2FiTGtSYXVRa2JkSFltWmZhWVc=
Once a token has been created and returned in the response, this can then be used to perform API requests for Imports.
To use the token for import requests an Authorization header needs to be set:
Authorization: Bearer <token>
Expiry
Tokens are valid only for 5 minutes.
Company Contact
The import methods are broken down into Standard, EployID and ExternalID imports, similar to the Import user interface. Thus there are 3 API methods for importing Companies and Contacts:
- Standard
- ExternalID
- EployID
Parameter
|
Values
|
Comment
|
---|---|---|
importData |
XML data Filename |
Data needs to be passed as a string, not bytes. This is the filename of the data file that was uploaded via FTP. |
uploadMethod |
Direct FtpUpload |
Direct is for sending a string of data. Is for when a file has been uploaded and a filename is passed in the importData parameter. |
ignoreMissingDropDownOptions | true or false | True will allow the tool to ignore missing Drop Down values such as Location, Industry etc. |
updateMatchedRecords | true or false | True will update records in Eploy that have matched data being imported. |
When using the Standard import method there are two extra parameters available:
Parameter
|
Values
|
Comment
|
---|---|---|
matchingCriteria_Comp |
CompName CompName_Address |
This allows the company data to be matched on the Company Name Matches the company data on Company Name and then attempts to match on address criteria in this order:
|
matchingCriteria_Cont |
ContFirstName_ContSurname_CompName ContFirstName_ContSurname_OR_ContEmail__CompName |
This matches the contact data on the Contact Firstname and Surname. This matches the contact data on the Contact Firstname and Surname or Email Address. N.B. All Contact matching criteria always also matches on Company Name. |
When using the External ID import method there are six extra parameters available:
sync_Comp |
true or false |
When this is true, you are in sync mode. This means that the import is expected to have all the companies in it that you want in the system, including existing ones. It is a full sync of companies, so companies that are not included will get their Status set to the value set in the next parameter. This mode is used to keep Eploy in sync with another system. |
deactivationStatus_Comp |
Company Status ID within the system. |
This is the status that Companies not included in the import will be set too. |
sync_Cont |
true or false |
When this is true, you are in sync mode. This means that the import is expected to have all the contacts in it that you want in the system, including existing ones. It is a full sync of contacts, so contacts that are not included will get their Status set to the value set in the next parameter. This mode is used to keep Eploy in sync with another system. |
deactivationStatus_Cont |
Company Status ID within the system. |
This is the status that Contacts not included in the import will be set too. |
sync_Usr |
true or false |
When this is true, you are in sync mode. This means that the import is expected to have all the users in it that you want in the system, including existing ones. It is a full sync of users, so users that are not included will get their Status set to the value set in the next parameter. This mode is used to keep Eploy in sync with another system. |
deactivationStatus_Usr |
1 or 0 |
For Users there is no status, 1 will keep the User active, 0 will deactivate them. |
Drop Down
The import methods are broken down into Standard, EployID and ExternalID imports, similar to the Import user interface. Thus there are 3 API methods for importing Drop Downs:
- Standard
- ExternalID
- EployID
All the methods take these parameters as a minimum:
Parameter
|
Values
|
Comment
|
---|---|---|
importData |
XML data Filename |
Data needs to be passed as a string, not bytes. This is the filename of the data file that was uploaded via FTP. |
uploadMethod |
Direct FtpUpload |
Direct is for sending a string of data. Is for when a file has been uploaded and a filename is passed in the importData parameter. |
dropDownType |
Departments |
This is the type of drop down the data is to be imported against. Custom drop downs can also be imported. The value for these can be found in the Drop Down Import Interface under the Drop Down Type field. |
ignoreMissingDropDownOptions | true or false | True will allow the tool to ignore missing Drop Down values such as Location, Industry etc. |
updateMatchedRecords | true or false | True will update records in Eploy that have matched data being imported. |
API Examples
REST Examples - Form URL Encoded
Company Contact - External ID
Request Headers:
POST /API/Import/CompanyContact/ExternalID HTTP/1.1
Host: abctrading.eploy.net
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Content-Length: length
Authorization: Basic aWtma2RKc0pwa1FCbnJleE5Kc0U6ZUV0bnpjS3RtbUJQaEJSRk1Ud1k=
Request Body:
importData=<Import><ImportRow><Comp_External_ID>EXT-15</Comp_External_ID><Cont_External_ID>EXT-1</Cont_External_ID><Cont_Addr1>146 Deramore Avenue 1</Cont_Addr1><Cont_Addr2>chadwell heath</Cont_Addr2><Cont_Addr3></Cont_Addr3><Cont_Branch></Cont_Branch><Cont_Comments></Cont_Comments><Cont_Country>UK</Cont_Country><Cont_Country_ID>186</Cont_Country_ID><Cont_Country_External_ID>UK</Cont_Country_External_ID><Cont_County>essex</Cont_County><Cont_Decision_Maker>1</Cont_Decision_Maker><Cont_DD_No></Cont_DD_No><Cont_Email>resourcing.manager@itssystems.co.uk</Cont_Email><Cont_Fax>0800 0734243</Cont_Fax><Cont_First_Name>Business</Cont_First_Name><Cont_Merge_Addr>0</Cont_Merge_Addr><Cont_Mob>0800 0734243</Cont_Mob><Cont_Pers_Email></Cont_Pers_Email><Cont_Pers_Mob></Cont_Pers_Mob><Cont_Pers_Tel></Cont_Pers_Tel><Cont_Position></Cont_Position><Cont_PostCode>rm6 4ta</Cont_PostCode><Cont_Ref></Cont_Ref><Cont_Salutation></Cont_Salutation><Cont_Surname>Partner</Cont_Surname><Cont_Tel>0800 0734243</Cont_Tel><Cont_Title>Mr</Cont_Title><Cont_Title_ID>1</Cont_Title_ID><Cont_Title_External_ID>MR</Cont_Title_External_ID><Cont_Town>romford</Cont_Town><Cont_Web_Addr></Cont_Web_Addr><Cont_Cont_Position>HRBP</Cont_Cont_Position><Cont_Cont_Position_ID>13</Cont_Cont_Position_ID><Cont_Cont_Position_External_ID></Cont_Cont_Position_External_ID><Cont_Reg_Cont>0</Cont_Reg_Cont><Cont_Occ_Cont>0</Cont_Occ_Cont><Cont_Third_Party_Cont>0</Cont_Third_Party_Cont><Cont_Status>Active</Cont_Status><Cont_Status_ID>1</Cont_Status_ID><Cont_Status_External_ID></Cont_Status_External_ID></ImportRow></Import>&uploadMethod=Direct&ignoreMissingDropDownOptions=true&updateMatchedRecords=true&sync_Comp=false&deactivationStatus_Comp=0&sync_Cont=false&deactivationStatus_Cont=0&sync_Usr=false&deactivationStatus_Usr=0
Drop Down - External ID
Request Headers:
POST /API/Import/DropDownList/ExternalID HTTP/1.1
Host: abctrading.eploy.net
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Content-Length: length
Authorization: Basic aWtma2RKc0pwa1FCbnJleE5Kc0U6ZUV0bnpjS3RtbUJQaEJSRk1Ud1k=
Request Body:
importData=<Import><ImportRow><External_ID>EXT-1</External_ID><Description>Commercial</Description><OrderID>0.00</OrderID><Active>0</Active></ImportRow></Import>&uploadMethod=Direct&dropDownType=Business+Areas&ignoreMissingDropDownOptions=true&updateMatchedRecords=true&matchingCriteria=DropDown_Description
REST Examples - JSON
Company Contact - External ID
Request Headers:
POST /API/Import/CompanyContact/ExternalID HTTP/1.1
Host: abctrading.eploy.net
Content-Type: application/
json; charset=utf-8
Content-Length: length
Authorization: Basic aWtma2RKc0pwa1FCbnJleE5Kc0U6ZUV0bnpjS3RtbUJQaEJSRk1Ud1k=
Request Body:
{ importData: "<Import><ImportRow><Comp_External_ID>EXT-15</Comp_External_ID><Cont_External_ID>EXT-1</Cont_External_ID><Cont_Addr1>146 Deramore Avenue 1</Cont_Addr1><Cont_Addr2>chadwell heath</Cont_Addr2><Cont_Addr3></Cont_Addr3><Cont_Branch></Cont_Branch><Cont_Comments></Cont_Comments><Cont_Country>UK</Cont_Country><Cont_Country_ID>186</Cont_Country_ID><Cont_Country_External_ID>UK</Cont_Country_External_ID><Cont_County>essex</Cont_County><Cont_Decision_Maker>1</Cont_Decision_Maker><Cont_DD_No></Cont_DD_No><Cont_Email>resourcing.manager@itssystems.co.uk</Cont_Email><Cont_Fax>0800 0734243</Cont_Fax><Cont_First_Name>Business</Cont_First_Name><Cont_Merge_Addr>0</Cont_Merge_Addr><Cont_Mob>0800 0734243</Cont_Mob><Cont_Pers_Email></Cont_Pers_Email><Cont_Pers_Mob></Cont_Pers_Mob><Cont_Pers_Tel></Cont_Pers_Tel><Cont_Position></Cont_Position><Cont_PostCode>rm6 4ta</Cont_PostCode><Cont_Ref></Cont_Ref><Cont_Salutation></Cont_Salutation><Cont_Surname>Partner</Cont_Surname><Cont_Tel>0800 0734243</Cont_Tel><Cont_Title>Mr</Cont_Title><Cont_Title_ID>1</Cont_Title_ID><Cont_Title_External_ID>MR</Cont_Title_External_ID><Cont_Town>romford</Cont_Town><Cont_Web_Addr></Cont_Web_Addr><Cont_Cont_Position>HRBP</Cont_Cont_Position><Cont_Cont_Position_ID>13</Cont_Cont_Position_ID><Cont_Cont_Position_External_ID></Cont_Cont_Position_External_ID><Cont_Reg_Cont>0</Cont_Reg_Cont><Cont_Occ_Cont>0</Cont_Occ_Cont><Cont_Third_Party_Cont>0</Cont_Third_Party_Cont><Cont_Status>Active</Cont_Status><Cont_Status_ID>1</Cont_Status_ID><Cont_Status_External_ID></Cont_Status_External_ID></ImportRow></Import>",
uploadMethod: "Direct",
ignoreMissingDropDownOptions: true,
updateMatchedRecords: true,
sync_Comp: false,
deactivationStatus_Comp: 0,
sync_Cont: false,
deactivationStatus_Cont: 0,
sync_Usr: false,
deactivationStatus_Usr: 0
}
Drop Down - External ID
Request Headers:
POST /API/Import/DropDownList HTTP/1.1
Host: abctrading.eploy.net
Content-Type: application/soap+xml; charset=utf-8
Content-Length: length
Authorization: Basic aWtma2RKc0pwa1FCbnJleE5Kc0U6ZUV0bnpjS3RtbUJQaEJSRk1Ud1k=
Request Body:
{ importData: "<Import><ImportRow><External_ID>EXT-1</External_ID><Description>Commercial</Description><OrderID>0.00</OrderID><Active>0</Active></ImportRow></Import>",
uploadMethod: "Direct",
dropDownType: "Business Areas",
ignoreMissingDropDownOptions: true,
updateMatchedRecords: true,
matchingCriteria: "DropDown_Description"
}
SOAP Examples
Company Contact
Request Headers:
POST /API/Import/CompanyContact HTTP/1.1
Host: abctrading.eploy.net
Content-Type: application/soap+xml; charset=utf-8
Content-Length: length
Authorization: Basic aWtma2RKc0pwa1FCbnJleE5Kc0U6ZUV0bnpjS3RtbUJQaEJSRk1Ud1k=
Request Body:
<?xml version='1.0' encoding='utf-8'?>
<soap12:Envelope xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' xmlns:xsd='http://www.w3.org/2001/XMLSchema' xmlns:soap12='http://www.w3.org/2003/05/soap-envelope'>
<soap12:Body>
<ExternalID xmlns='http://tempuri.org/'>
<importData>
<![CDATA[
<Import>
<ImportRow>
<Comp_External_ID>EXT-15</Comp_External_ID>
<Cont_External_ID>EXT-1</Cont_External_ID>
<Cont_Addr1>146 Deramore Avenue 1</Cont_Addr1>
<Cont_Addr2>chadwell heath</Cont_Addr2>
<Cont_Addr3></Cont_Addr3>
<Cont_Branch></Cont_Branch>
<Cont_Comments></Cont_Comments>
<Cont_Country>UK</Cont_Country>
<Cont_Country_ID>186</Cont_Country_ID>
<Cont_Country_External_ID>UK</Cont_Country_External_ID>
<Cont_County>essex</Cont_County>
<Cont_Decision_Maker>1</Cont_Decision_Maker>
<Cont_DD_No></Cont_DD_No>
<Cont_Email>resourcing.manager@itssystems.co.uk</Cont_Email>
<Cont_Fax>0800 0734243</Cont_Fax>
<Cont_First_Name>Business</Cont_First_Name>
<Cont_Merge_Addr>0</Cont_Merge_Addr>
<Cont_Mob>0800 0734243</Cont_Mob>
<Cont_Pers_Email></Cont_Pers_Email>
<Cont_Pers_Mob></Cont_Pers_Mob>
<Cont_Pers_Tel></Cont_Pers_Tel>
<Cont_Position></Cont_Position>
<Cont_PostCode>rm6 4ta</Cont_PostCode>
<Cont_Ref></Cont_Ref>
<Cont_Salutation></Cont_Salutation>
<Cont_Surname>Partner</Cont_Surname>
<Cont_Tel>0800 0734243</Cont_Tel>
<Cont_Title>Mr</Cont_Title>
<Cont_Title_ID>1</Cont_Title_ID>
<Cont_Title_External_ID>MR</Cont_Title_External_ID>
<Cont_Town>romford</Cont_Town>
<Cont_Web_Addr></Cont_Web_Addr>
<Cont_Cont_Position>HRBP</Cont_Cont_Position>
<Cont_Cont_Position_ID>13</Cont_Cont_Position_ID>
<Cont_Cont_Position_External_ID>
</Cont_Cont_Position_External_ID>
<Cont_Reg_Cont>0</Cont_Reg_Cont>
<Cont_Occ_Cont>0</Cont_Occ_Cont>
<Cont_Third_Party_Cont>0</Cont_Third_Party_Cont>
<Cont_Status>Active</Cont_Status>
<Cont_Status_ID>1</Cont_Status_ID>
<Cont_Status_External_ID></Cont_Status_External_ID>
</ImportRow>
</Import>
]]>
</importData>
<uploadMethod>Direct</uploadMethod>
<ignoreMissingDropDownOptions>true</ignoreMissingDropDownOptions>
<updateMatchedRecords>true</updateMatchedRecords>
<sync_Comp>false</sync_Comp>
<deactivationStatus_Comp>0</deactivationStatus_Comp>
<sync_Cont>false</sync_Cont>
<deactivationStatus_Cont>0</deactivationStatus_Cont>
<sync_Usr>false</sync_Usr>
<deactivationStatus_Usr>0</deactivationStatus_Usr>
</ExternalID>
</soap12:Body>
</soap12:Envelope>
Drop Down
Request Headers:
POST /API/Import/DropDownList HTTP/1.1
Host: abctrading.eploy.net
Content-Type: application/soap+xml; charset=utf-8
Content-Length: length
Authorization: Basic aWtma2RKc0pwa1FCbnJleE5Kc0U6ZUV0bnpjS3RtbUJQaEJSRk1Ud1k=
Request Body:
<?xml version='1.0' encoding='utf-8'?>
<soap12:Envelope xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' xmlns:xsd='http://www.w3.org/2001/XMLSchema' xmlns:soap12='http://www.w3.org/2003/05/soap-envelope'>
<soap12:Body>
<ExternalID xmlns='http://tempuri.org/'>
<importData>
<![CDATA[ <Import> <ImportRow> <External_ID>EXT-1</External_ID> <Description>Commercial</Description> <OrderID>0.00</OrderID> <Active>0</Active> </ImportRow> <ImportRow> <External_ID>EXT-2</External_ID> <Description>Industrial 2</Description> <OrderID>0.00</OrderID> <Active>1</Active> </ImportRow> <ImportRow> <External_ID>FIN</External_ID> <Description>Finance 2</Description> <OrderID>0.00</OrderID> <Active>1</Active> </ImportRow> </Import> ]]> </importData>
<uploadMethod>Direct</uploadMethod>
<dropDownType>Business Areas</dropDownType>
<ignoreMissingDropDownOptions>true</ignoreMissingDropDownOptions>
<updateMatchedRecords>true</updateMatchedRecords>
</ExternalID>
</soap12:Body>
</soap12:Envelope>
Use Cases & Scenarios
When begining to use the API to synchronize Contact, Company and Drop Down List data, there may be several scenarios that affect how you should introduce the synchronization functionality. The most effective method for syncronizing data is using the External ID Import Type. This allows records to be uniquely identified with a reference that is maintained outside of Eploy, allowing you to ensure duplicates are not created while not needing to know the Eploy IDs for records. While it is also possible to create and update records using the Standard Import Type, this relies on every company name and contact name / email address being unique, to avoid duplication. The Standard import also limits you from being able to update these key details, for example if a department or contact changes their name.
Therefore, for new Eploy systems, when setting up the Company Structure and Contacts for the fist time, performing an External ID Import will allow the External IDs to be set in preparation for introducing the synchronization.
Existing Contact & Company Data
If you have existing records in Eploy, these are unlikely to have External IDs to begin with, therefore a one-off Standard or EployID Import may be necessary to set these up. The existing data can be exported from Eploy as a CSV file using a Document merge by selecing the 'Doc Merge' option and choosing CSV as the 'Merge To' option. This will contain the Eploy IDs for the existing records, which can be used to perform an EployID import to set the ExternalIDs. ExternalIDs can also be set using the Standard import, as long as all Company names/Contact name/email combinations are unique.
Existing Drop Down List Data
The Eploy IDs for Drop Down List entries are visible on the Drop Down Lists Admin page (Admin > Drop Down Lists). These can be used to perform an initial update of existing drop down entires to set the External IDs when preparing to introduce a Drop Down synchronization. External Drop Down IDs can also be set using the Standard import, as long as their descriptions are unique.
User Permission Templates
If introducing a Contact synchronization that needs to create user records and set permissions, the Usr_Copy_Usr_ID field can be used to copy permissions from an existing user in Eploy. The source user does not necessarily need to be active, therefore you can prepare user permission templates simply by adding User records, assigning the relevant permissions and then deactivating them (noting the User IDs for use within the Usr_Copy_Usr_ID field when calling the API).