| Table of Contents |
|---|
Summary
This article covers the recommended and proper order for importing customer data into EngageIP. When importing large amounts of data it is recommended to use the DataMigration Utility.
Before you can proceed with any import process here please complete follow the kb article: Data Migration – Import Methods and Configuration.
XML Format
| Note |
|---|
Warning: Format is important. XML files for the migrator are case sensitive for element names and element values (those of which are being matched to data already in the system such as bill groups, or credit rating items). |
| Info |
|---|
Special Characters Note: If you have special characters ( % ^ & * # @ ! ) in usernames for example when importing and its causing issues, you can replace the special character with its ASCII code and it will import as the correct symbol. |
Importing Owner Accounts
See the System Configuration Import kb article for details on importing Owner accounts.
...
| Code Block |
|---|
<User Name="test_customer" Password="test" Owner="admin" Role="Admin" Culture="English" Currency="USA" Language="English" CreatedDate="1/15/2007 12:00:00 AM" StatusType="MyCustomAccountStatusType" TaxCode="Residential" BillGroup="Default" CreditRating="Default" BillDay="1" DisableReason="Cancelled"/> |
Name | Name of user, can be alpha numeric, any unique identifier for customers, companies or accounts |
‘Bob McCowan’ or ‘CUST2838382’ or ‘3334445555’ etc. | |
Password | Password belonging to the user account for login to |
the AdminPortal | ‘password’ or ‘FidDz73Ds’ | |
Owner | Name of the Owner the country belongs to | this will be based on previous import |
Role | The intended role of the account once in the system | Predefined by previous import, Customer role or Admin role |
Culture | Culture of account | Predefined in database table called 'Culture'. The name of the culture needs to exist so that it can look up the name and enter the ID in the USER table. |
Currency | The alpha character currency of account | ‘USA’ or ‘USD’ for United States or ‘CAD’ for Canada, or ‘EUR’ |
Language | The primary language of the account, to be used when determining the language the interface displays in | ‘English’, ‘Spanish’, etc. |
CreatedDate | The creation date of the account if it exists, or enter the same date for all accounts | ‘10/10/2006 11:00:14 AM’. Format based on system configuration, mm/dd/yyyy or dd/mm/yyyy depending on regional settings on the SQLserver |
StatusType | Status of the account on import, this is a configured account status type | These are based on already imported values in the interface. May be ‘Enabled’, ‘Active’, see your previously imported StatusTypes for this. |
TaxCode | Name of the customers intended taxcode | This is predefined in EngageIP by previous import |
BillGroup | Name of the billgroup customer should be using | This is predefined in EngageIP by previous import |
CreditRating | Name of credit rating in system | This is predefined in EngageIP by previous import |
BilllDay | Day on which to bill customer recurring | this is a numeric value, 1, 2, through 28 (no 29, 30, 31). This is the day on which the customer will bill every month |
Disable Reason | This is a cancelation reason which is not used anymore | Can be left blank |
Importing Account Contacts
| Code Block |
|---|
<Contact User="billingtest" ContactName="test test" ContactFirstName="test" ContactLastName="test" ContactTitle="Billing Contact" ContactType="Billing Contact" ContactCompany="CompanyName" /> |
User | 'jsmith' or '5192490508' or 'Company X' |
|
ContactName | Customer name or contact name | 'John Smith' |
ContactFirstName | First name of contact | 'John' |
ContactLastName | Last name of contact | 'Smith' |
ContactTitle | Title of contact | 'CEO' or 'Network Administrator' or 'Director of Marketing' |
ContactType | Contact type as defined in interface | Predefined contact type on setup tab, usually 'Billing Contact' or 'Technical Contact' or 'Administrative Contact' but not limited to those. |
ContactCompany | Company Name | 'Logisense Corporation' or Company X |
Importing Account Contact's Email Address
...
'Email Address' contact point type must exist, no other names will buseree found by the system.
Contact Name = Firstname + Lastname on the contact
User | Account identifier | 'jsmith' or '5192490508' or 'Company X' |
ContactName | Customer name or contact name. This name needs to exist already on original Contact.xml file | Preexisting value here based on contact.xml. 'John Smith' |
Email address of contact | 'username@domain.com' | |
ContactType | Contact type as defined in interface | Predefined contact type on setup tab, usually 'Billing Contact' or 'Technical Contact' or 'Administrative Contact' but not limited to those. |
Importing Account Contact's Phone Number
| Code Block |
|---|
<ContactPhone User="bsmith" ContactName="Billy Smith" Phone="15196526432" ContactType="Billing" ContactPointType="Phone" /> |
User | Account identifier | 'jsmith' or '5192490508' or 'Company X' |
ContactName | Customer name or contact name | 'John Smith' |
Phone | Phone number for billing contact in this case | 5192490508 or '011 345 4565 6765' |
ContactType | Contact type as defined in interface | Predefined contact type on setup tab, usually 'Billing Contact' or 'Technical Contact' or 'Administrative Contact' but not limited to those. |
ContactPointType | Name of contact point type | This should exist already in the system 'Work Phone' |
Importing Account Contact's Fax Number
...
| Code Block |
|---|
<Company User="logisense" Company="LogiSense Corporation" /> |
User | Name of user account this applies to | bsmith |
Company | Name of the company to import | 'LogiSense Corporation' (note: Import does not allow '&' ampersand. Replace with 'and') |
Importing Child Accounts
Sets up sub account relationships between accounts. This can be at any level.
| Warning |
|---|
Alert: this approach is only to be used for initial import. If this import is used after a parent account has transactions / invoices, the invoices will not transfer and display correctly on the new parent. This should never be used on accounts where transactions / invoices exist. If it has been used in this fashion, you can 'reset' the invoices by using the tools tab on the account to move it back up to a parent and back down as the child, this executes the logic to move the invoices as expected to the new parent account. |
| Code Block |
|---|
<Child Name="userchild" Parent="userparent"/> |
Name | Name of sub account | 'Sally Jones' (where this is the name of a daughter in this example) |
Parent | Name of direct parent account or main account. This is the account the user should be directly under | 'Mr Jones' (this is the name of the father in this case, orparent account) |
Importing Account Invoices
To Add Debits
| Info |
|---|
Note: when entering the package element, this refers to the Service name specifically as that is what this will be applied to rather then the overall package (often packages and services have the same names so this is a key item). Enter Service name here. |
For taxes to import, ensure you have a taxcode that exists and that the taxcode also has tax rates associated, up to four rates if you want the rates to associate here. Without this config, the tax value will be ignored.
| Code Block |
|---|
<Invoice User="ejones" Date="1/31/2007 12:00:00 AM" Debit="0" Tax1="0" Tax2="0" Tax3="0" Tax4="0" TaxCode="Residential" Description="Opening Balance" Package="Opening Balance" PeriodStart="mm/dd/yyyy" PeriodEnd="mm/dd/yyyy" /> |
Sample Debit import file here:
| View file | ||
|---|---|---|
|
To Add Credits
| Info |
|---|
Note: to add a credit a negative debit value is used (as shown below). |
| Code Block |
|---|
<Invoice User="ejones" Date="1/31/2007 12:00:00 AM" Debit="-10" Tax1="0" Tax2="0" Tax3="0" Tax4="0" TaxCode="Residential" Description="Opening Balance" Package="Opening Balance" PeriodStart="mm/dd/yyyy" PeriodEnd="mm/dd/yyyy" /> |
...
Template credit import file:
| View file | ||
|---|---|---|
|
| Info |
|---|
Note: along with the tag, you need at least one element, i.e. CloseInvoice="". CloseInvoice element does not need a value, it simply needs to exist as shown. The import tool when seeing this invoice close tag assumes all other invoices in the system are closed and so it will close anything that is OPEN in the system. It is not to be used on a system that has valid OPEN invoices. |
For example, the below will create two invoices. One for January (then you can see the close tag) and another for February (with another close tag after it). So you can group these 'transactions' into their individual invoices as needed.
...
The generic method is below, this allows more elements such as defining the PaymentType so you can enter credit card or other predefined types.
| Info |
|---|
Note: you need to update the owner name in the tags to use this. |
| Code Block |
|---|
<Payment User="/User=admin" Date="2017-1-1" Amount="88.84" Detail="Lock Box" CheckNumber="19243" PaymentType="/Owner=Logisense Corporation/PaymentType=Check" PaidBy_User="/User=admin" Disbursed="False" AutomaticDisburse="True" Deposit="False" AddedBy_User="/User=admin" PostingDate="2017-1-1" BatchNumber="0"/> |
...
| Code Block |
|---|
<CloseInvoice CloseInvoice="" /> <Invoice User="bsmithy" Date="6/30/2006 12:00:00 AM" Debit="26.7" Tax1="0" Tax2="0" Tax3="0" Tax4="0" Description="Opening Balance" PeriodStart="mm/dd/yyyy" PeriodEnd="mm/dd/yyyy" /> |
User | Name of existing account | 'ejones' |
Date | Date of transaction | '6/30/2006 12:00:00 AM' |
Debit | Value of debit | '26.7' or '23.15' (these need to be absolute values) |
Credit | Value of credit | 0 (these need to be absolute values) |
Tax1 | Value of tax charged | 0 or '1.47' |
Tax2 | Value of tax charged | 0 or '1.47' |
Tax3 | Value of tax charged | 0 or '1.47' |
Tax4 | Value of tax charged | 0 or '1.47' |
TaxCode | Name of taxcode that exists in the system | 'State Taxcode' |
Description | Description of transaction | 'Opening balance' |
Package | Name of SERVICE (Package is the legacy name for service) that the transaction applies to | 'Broadband Wifi Access' |
PeriodStart | Service period dates |
|
PeriodEnd | Service period dates |
|
User | Name of account under which payment should b e applied. May be a child of bsmith as shown in above example | 'bsmith' or a child of bsmith 'frank' |
Date | Date of transaction | 1/18/2007 2:26:28 PM |
Credit | Value of credit, in dollars and cents | '2.0000' |
Description | Description of payment | 'Credit Card payment' |
Importing Opening Balances
...
| Code Block |
|---|
<Payment User="admin" Date="10/21/2004 2:21:35 PM" Credit="425.0000" PaymentType="Cash" Description="Batch Payment" /> |
User | Name of account under which payment should b e applied. May be a child of bsmith as shown in above example | 'bsmith' or a child of bsmith 'frank' |
Date | Date of transaction | 1/18/2007 2:26:28 PM |
Credit | Value of credit, in dollars and cents | '2.0000' |
Description | Description of payment | 'Credit Card payment' |
Importing UserPackage
The account's package. An account can have multiple packages which will bill according to their Bill Cycle. Any package added which does not match the billing cycle will be prorated to the account's bill cycle. .
...
For below, click 'Use Generic':
| Code Block |
|---|
<import> <UserPackage Package="/Owner=Logisense Corporation/Package=testonce" User="/User=admin" CreatedDate="02/02/2018" NextBillDate="02/02/2018" Name="testonce" StatusType="Active" Pending="0" LastStatusChangedDate="02/02/2018" EffectiveDate="02/02/2018" LastUpdatedDate="02/02/2018" BulkQuantity="1" UserPackageStatusType="/Owner=Logisense Corporation/UserPackageStatusType=Enable" CreatedBy_User="admin" ReferenceName="test"/> </import> |
| Info |
|---|
Note: Created Date equals 'Today' when imported. |
User | Name or letter combination that is restricted | English or 'Residential Customer Invoice 2 Page' |
Name | Name of the package that will show to the customer and in reports | this package should exist from previous import ofpackage.xml |
NextBillDate | Date on which the package will be next for the customer | 2/18/2007 |
Importing UserService
This is a generic method for importing user-services (non-optional)
| Code Block |
|---|
<UserService Service="/Owner=Logisense Corporation/Service=Global Bucketting" User="MyTestUser" CreatedDate="2017-07-07 16:43:21" UserPackageID="67350" Name="PackageName" Amount="0.00" Optional="False" OneTimeAmount="0.00" LastUpdateDate="2017-07-07 16:43:21" CreatedBy_User="admin" /> |
Importing Optional UserService
| Tip |
|---|
New in EngageIP 9.3.3 |
| Info |
|---|
Note: 'UserService ServiceID' is the ID of the Service in the Product Catalog. |
| Code Block |
|---|
<UserService ServiceID="1" UserID="4" OptionalServiceStartDate="2019-12-20 00:00:00" UserPackageID="1" Optional="True"/> |
...
| Code Block |
|---|
<UserPackageAttributeDiscount DiscountType = "Price" Amount="30.00" User="bsmithy" UserPackage="Monthly DialUp" UserService="Dialup"/> |
Discount Type | Type of the discount | Fixed | Price | Percent |
Amount | Value of the discount | 29.99 or 30 |
User | User to which the discount should be applied | bsmith |
UserPackage | Package to which the discount should be applied | Monthly DialUp |
UserService | Service to which the discount should be applied | Dialup |
Importing User Package Services
Attach services to packages in EngageIP
Code Block <?xml version="1.0"?> <PackageServices> <PackageService Package="Annual DSL" Service="Setup" Owner="Quality_Assurance"/> <PackageService Package="Annual DSL" Service="DSL" Owner="Quality_Assurance"/> <PackageService Package="Monthly DialUp" Service="DialUp" Owner="Quality_Assurance"/> <PackageService Package="PackageAttribute" Service="DialUp" Owner="Quality_Assurance"/> <PackageService Package="VOIP" Service="VOIP" Owner="Quality_Assurance" /> </PackageServices>
| Info |
|---|
Note: if you are importing one time services that have billed already in another system and you simply want the service to import without again billing / charging, you would need to update the table called 'UserService', and update 'BillTimes', set it to zero. NULL reflects recurring services, '1' reflects that the service needs to be billed, and '0' reflects that the one time service has been billed. |
Importing UserAttributes
Apply expiry date to user account
UserAttributeChangeUserStatusType
| Info |
|---|
Note: this is the generic method. The status type of 'Disabled' must exist, the date format in this case is mm/dd/yyyy |
For correct prorating, ensure that the time is completed as well, in this case, the end of day on the 31st is when the account should be canceled and if prorating applies, that will be considered
...
Applies TaxClass to user specifically
| Info |
|---|
Note: this uses the 'generic' format, as different from most of the other import items. |
| Code Block |
|---|
<UserAttributeTaxClass TaxClass="/Owner=Logisense Corporation/TaxClass=Hardware" User="/User=bsmith" /> <UserAttributeTaxClass TaxClass="/Owner=Logisense Corporation/TaxClass=Hardware" User="/User=mike" /> |
...
| Code Block |
|---|
<Ticket User="tasklist" Reference="2 test" Subject="test" Description="" Resolution="" Assignedto="bsmithy" Loggedby="bsmithy" Date="1/15/2007 12:51:52 PM" Timespent="0" Status="Open" Priority="Normal" Closedby="User" Dateclosed="mm/dd/yyyy" Category="Support" Contactmethod="Email" Fromaddress="bsmithy@logisense.com" Totaltimespent="0" Currenttimespent="0" Lastmodifiedby="bsmithy" Lastmodifieddate="1/15/2007 12:51:52 PM" Hiddenresolution="" Showtouser="False" Duedate="1/15/2007 12:00:00 AM" TicketID="2" /> |
User | Account identifier | 'jsmith' or '5192490508' or 'Company X' |
Reference |
|
|
Subject | Subject of ticket | 'customer DSL is slow' |
Description | Description of ticket |
|
Resolution | Resolution section of ticket |
|
AssignedTo | Username of admin this is assigned to | 'bsmith' |
Loggedby | Username of account that logged the ticket | 'ljones' |
Date | Date the ticket was added | '1/15/2007 12:51:52 PM' |
TimeSpent | Value in minutes of the time spent | 0 |
Status | Current status of the ticket | 'Open', 'Closed' |
Priority | Priority of the ticket | Low, Normal, High (these will be configured in Adminportalalready, match the names of preexisting priorities) |
ClosedBy | Username of admin that closed the ticket if status is closed | 'nburns' |
Dateclosed | Date the ticket was closed | '2/18/2007 12:51:52 PM' |
Category | Category of ticket | predefined on setup tab |
Contactmethod | The method used to contact customer support |
|
Fromaddress | bsmithy@logisense.com |
|
Totaltimespent | Total time in minutes spend on ticket so far | 0 |
Currenttimespent | Value in minutes of current time spend | 0 |
Lastmodifiedby | Username of admin that modified the ticket | bsmithy |
Hiddenresolution | Text from ticket that was hidden from end user (background discussion) | text that was on ticket but hidden from customer |
Showtouser | Flag defining whether end user (customer) can see this ticket if logged into customerportal | True or False |
Duedate | Date on which the ticket should be completed | 1/15/2007 12:00:00 AM |
TicketID | ID reference for ticket | 32194 |
Importing Ticket Tracking Records
Ticket Tracking records are the detail attached to the ticket, the inline comments or appended text on tickets.
| Info |
|---|
Note: the ticket is the core ticket. Ticket Tracking is the detail of the ticket. |
An example of the ticket tracking XML is shown below:
...