forked from paulyasi/citrusdb
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathdocumentation.html
4197 lines (3456 loc) · 136 KB
/
documentation.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"
lang="en" xml:lang="en">
<head>
<title>CitrusDB 3.0 Manual</title>
<meta http-equiv="Content-Type" content="text/html;charset=utf-8"/>
<meta name="author" content="Paul Yasi"/>
<style type="text/css">
<!--/*--><![CDATA[/*><!--*/
html { font-family: serif; font-size: 12pt; }
.title { text-align: center; }
.todo { color: red; }
.done { color: green; }
.tag { background-color:lightblue; font-weight:normal }
.target { }
.timestamp { color: grey }
.timestamp-kwd { color: CadetBlue }
p.verse { margin-left: 3% }
pre {
border: 1pt solid #AEBDCC;
background-color: #F3F5F7;
padding: 5pt;
font-family: courier, monospace;
font-size: 90%;
overflow:auto;
}
table { border-collapse: collapse; }
td, th { vertical-align: top; }
dt { font-weight: bold; }
div.figure { padding: 0.5em; }
div.figure p { text-align: center; }
.linenr { font-size:smaller }
.code-highlighted {background-color:#ffff00;}
.org-info-js_info-navigation { border-style:none; }
#org-info-js_console-label { font-size:10px; font-weight:bold;
white-space:nowrap; }
.org-info-js_search-highlight {background-color:#ffff00; color:#000000;
font-weight:bold; }
/*]]>*/-->
</style>
<script type="text/javascript">
<!--/*--><![CDATA[/*><!--*/
function CodeHighlightOn(elem, id)
{
var target = document.getElementById(id);
if(null != target) {
elem.cacheClassElem = elem.className;
elem.cacheClassTarget = target.className;
target.className = "code-highlighted";
elem.className = "code-highlighted";
}
}
function CodeHighlightOff(elem, id)
{
var target = document.getElementById(id);
if(elem.cacheClassElem)
elem.className = elem.cacheClassElem;
if(elem.cacheClassTarget)
target.className = elem.cacheClassTarget;
}
/*]]>*/-->
</script>
</head><body>
<h1 class="title">CitrusDB 3.0 Manual</h1>
<div id="table-of-contents">
<h2>Table of Contents</h2>
<div id="text-table-of-contents">
<ul>
<li><a href="#sec-1">1 Introduction </a></li>
<li><a href="#sec-2">2 Chapter 1: Installation </a>
<ul>
<li><a href="#sec-2.1">2.1 Installing the Main Internal Application </a></li>
<li><a href="#sec-2.2">2.2 Customer Self-Service Portal</a></li>
<li><a href="#sec-2.3">2.3 Upgrading CitrusDB </a></li>
</ul>
</li>
<li><a href="#sec-3">3 Chapter 2: Setup </a>
<ul>
<li><a href="#sec-3.1">3.1 Login </a></li>
<li><a href="#sec-3.2">3.2 Organization Configuration </a></li>
<li><a href="#sec-3.3">3.3 Settings </a></li>
<li><a href="#sec-3.4">3.4 Users </a></li>
<li><a href="#sec-3.5">3.5 Groups </a></li>
<li><a href="#sec-3.6">3.6 Billing Types </a></li>
<li><a href="#sec-3.7">3.7 Holidays </a></li>
<li><a href="#sec-3.8">3.8 Services </a>
<ul>
<li><a href="#sec-3.8.1">3.8.1 Adding Your Services </a></li>
</ul>
</li>
<li><a href="#sec-3.9">3.9 Linking Services with Setup Fees, and Bundled Services </a></li>
<li><a href="#sec-3.10">3.10 Taxes and Fees </a>
<ul>
<li><a href="#sec-3.10.1">3.10.1 Linking taxes </a></li>
</ul>
</li>
<li><a href="#sec-3.11">3.11 Field Assets </a></li>
<li><a href="#sec-3.12">3.12 Searches </a></li>
<li><a href="#sec-3.13">3.13 Attribute/Option URL Links </a></li>
<li><a href="#sec-3.14">3.14 Setup Finished </a></li>
</ul>
</li>
<li><a href="#sec-4">4 Chapter 3: Customer Service </a>
<ul>
<li><a href="#sec-4.1">4.1 Searching for Customers </a></li>
<li><a href="#sec-4.2">4.2 Customer Records </a></li>
<li><a href="#sec-4.3">4.3 Billing Records </a></li>
<li><a href="#sec-4.4">4.4 Editing Billing Records </a></li>
<li><a href="#sec-4.5">4.5 Invoice Maintenance </a></li>
<li><a href="#sec-4.6">4.6 Individual Billing Record Refund Report </a></li>
<li><a href="#sec-4.7">4.7 Prorate Services </a></li>
<li><a href="#sec-4.8">4.8 Service Records </a>
<ul>
<li><a href="#sec-4.8.1">4.8.1 Example Billing Combinations </a></li>
<li><a href="#sec-4.8.2">4.8.2 Edit Service Records </a></li>
<li><a href="#sec-4.8.3">4.8.3 Service History </a></li>
</ul>
</li>
<li><a href="#sec-4.9">4.9 Customer Notes </a>
<ul>
<li><a href="#sec-4.9.1">4.9.1 View notes sent to you </a></li>
<li><a href="#sec-4.9.2">4.9.2 Editing a customer support note </a></li>
</ul>
</li>
<li><a href="#sec-4.10">4.10 Billing Status </a></li>
<li><a href="#sec-4.11">4.11 Billing History </a></li>
<li><a href="#sec-4.12">4.12 Payment History </a></li>
<li><a href="#sec-4.13">4.13 Billing Details </a></li>
<li><a href="#sec-4.14">4.14 Re-Running Declined Credit Cards </a></li>
<li><a href="#sec-4.15">4.15 Welcome Letters </a></li>
</ul>
</li>
<li><a href="#sec-5">5 Chapter 4: Billing and Payments </a>
<ul>
<li><a href="#sec-5.1">5.1 Billing Tools </a>
<ul>
<li><a href="#sec-5.1.1">5.1.1 Credit card batches </a></li>
<li><a href="#sec-5.1.2">5.1.2 Invoice printing </a></li>
<li><a href="#sec-5.1.3">5.1.3 E-Invoice emailing </a></li>
<li><a href="#sec-5.1.4">5.1.4 Entering Payments </a></li>
<li><a href="#sec-5.1.5">5.1.5 Processing Refund </a></li>
<li><a href="#sec-5.1.6">5.1.6 Importing New Accounts </a></li>
<li><a href="#sec-5.1.7">5.1.7 Importing Service Usage </a></li>
<li><a href="#sec-5.1.8">5.1.8 Importing Credit Card Changes </a></li>
</ul>
</li>
<li><a href="#sec-5.2">5.2 Reports </a>
<ul>
<li><a href="#sec-5.2.1">5.2.1 Customer Summary </a></li>
<li><a href="#sec-5.2.2">5.2.2 Revenue Report </a></li>
<li><a href="#sec-5.2.3">5.2.3 Refund Report </a></li>
<li><a href="#sec-5.2.4">5.2.4 Past Due Report </a></li>
<li><a href="#sec-5.2.5">5.2.5 Payment Status Report </a></li>
<li><a href="#sec-5.2.6">5.2.6 Service Report </a></li>
<li><a href="#sec-5.2.7">5.2.7 Source Report </a></li>
<li><a href="#sec-5.2.8">5.2.8 Exempt Report </a></li>
<li><a href="#sec-5.2.9">5.2.9 Print Notices </a></li>
<li><a href="#sec-5.2.10">5.2.10 Service Growth </a></li>
</ul></li>
</ul>
</li>
<li><a href="#sec-6">6 Chapter 5: Server Administration and Integration </a>
<ul>
<li><a href="#sec-6.1">6.1 Backups </a></li>
<li><a href="#sec-6.2">6.2 Custom Modules </a></li>
<li><a href="#sec-6.3">6.3 Account Activation and Deactivation </a></li>
<li><a href="#sec-6.4">6.4 Credit Card Batch Exports Format </a></li>
<li><a href="#sec-6.5">6.5 Credit Card Batch Imports Format </a></li>
<li><a href="#sec-6.6">6.6 New Accounts Data Format </a></li>
<li><a href="#sec-6.7">6.7 Service Usage Data </a></li>
<li><a href="#sec-6.8">6.8 Credit Card Change Format </a></li>
<li><a href="#sec-6.9">6.9 Automation </a>
<ul>
<li><a href="#sec-6.9.1">6.9.1 Automatic Credit Card Billing </a></li>
<li><a href="#sec-6.9.2">6.9.2 Automatic Invoice Printing </a></li>
<li><a href="#sec-6.9.3">6.9.3 Automatic Invoice Emailing </a></li>
</ul></li>
</ul>
</li>
<li><a href="#sec-7">7 Chapter 6: Data Security Implementation Guide </a>
<ul>
<li><a href="#sec-7.1">7.1 CitrusDB Configuration </a></li>
<li><a href="#sec-7.2">7.2 Physical Data Center </a></li>
<li><a href="#sec-7.3">7.3 Passwords </a></li>
<li><a href="#sec-7.4">7.4 Encrypting and Decrypting card data </a>
<ul>
<li><a href="#sec-7.4.1">7.4.1 Encrypting existing card data </a></li>
<li><a href="#sec-7.4.2">7.4.2 Changing encryption keys for card data </a></li>
</ul>
</li>
<li><a href="#sec-7.5">7.5 Purge old cardholder data </a>
<ul>
<li><a href="#sec-7.5.1">7.5.1 Remove Exported Batch files </a></li>
<li><a href="#sec-7.5.2">7.5.2 Remove Canceled Customer Records </a></li>
</ul>
</li>
<li><a href="#sec-7.6">7.6 Logging of user activity </a></li>
<li><a href="#sec-7.7">7.7 Keeping Up-to-Date </a></li>
</ul>
</li>
<li><a href="#sec-8">8 Online Resources </a></li>
<li><a href="#sec-9">9 Appendix A: GPG Commands </a>
<ul>
<li><a href="#sec-9.1">9.1 Creating A Key </a></li>
<li><a href="#sec-9.2">9.2 Listing Public Keys </a></li>
<li><a href="#sec-9.3">9.3 Listing Private Keys </a></li>
<li><a href="#sec-9.4">9.4 Export Public Key </a></li>
<li><a href="#sec-9.5">9.5 Export Private Key </a></li>
<li><a href="#sec-9.6">9.6 Importing Public Key </a></li>
<li><a href="#sec-9.7">9.7 Import Private Key </a></li>
<li><a href="#sec-9.8">9.8 Delete a Public Key </a></li>
<li><a href="#sec-9.9">9.9 Delete a Private Key </a></li>
<li><a href="#sec-9.10">9.10 Encrypt Data with Ascii Armor </a></li>
<li><a href="#sec-9.11">9.11 Decrypt Data </a></li>
<li><a href="#sec-9.12">9.12 Edit a Key </a></li>
<li><a href="#sec-9.13">9.13 Key Signing </a></li>
<li><a href="#sec-9.14">9.14 Key Trust </a></li>
<li><a href="#sec-9.15">9.15 Revoke a key </a></li>
<li><a href="#sec-9.16">9.16 Command Options </a></li>
</ul>
</li>
<li><a href="#sec-10">10 Appendix B: OpenSSL Certificate </a></li>
</ul>
</div>
</div>
<div id="outline-container-1" class="outline-2">
<h2 id="sec-1">1 Introduction </h2>
<div id="text-1">
<p>CitrusDB is an open source customer service and billing
database. It can be used by customer service personnel to provide
sales and support to customers, and by billing staff to bill
customers for their services via invoices and credit card batches.
Customers may access the Online customer account manager to view
their services, billing history, and make service and support
requests online.
</p>
<p>
Requirements:
<ul>
<li> PHP 5.2 or greater
<li> MySQL 4.1 or greater
<li> An SSL Certificate for the domain where it will be installed (Can be self signed)
<li> A GPG Key Pair if you are storing credit card data
<li> A Web Browser with Cookies and Javascript
</ul>
</p>
</div>
</div>
<div id="outline-container-2" class="outline-2">
<h2 id="sec-2">2 Chapter 1: Installation </h2>
<div id="text-2">
<p>Before you install CitrusDB you should check whether a web
server with the PHP module, and MySQL database are installed on your
server. To check whether MySQL, and PHP are installed in
your server correctly you can upload a simple PHP file to your
server that contains the following code:
</p>
<pre class="example">
<?php
phpinfo();
?>
</pre>
<p>
View your uploaded file in a web browser by going to your site, eg:
www.yourname.com/file.php This will show you what version of PHP
you are running and a lot of information about your PHP
installation. Further down the screen there will be a section
about your MySQL installation that will confirm whether MySQL is
supported by your PHP installation. If the file you uploaded does
not load, give an error, or does not show anything about MySQL,
your server is not configured correctly. You will need to fix this
before you continue.
</p>
<p>
There are many methods to install a web server, MySQL and PHP on your
server. On Linux you will usually be able to find a package
available for your distro that you can install via a package
manager like synaptic, apt-get, or yum. Mac OS X already has
Apache installed by default, all you'll need to do is enable PHP
and install MySQL or you can use a pre-built package like XAMPP.
If you are using Windows you can try the pre-built packages like
XAMPP that include all the pieces you need for Apache, MySQL, and
PHP. Microsoft also maintains PHP packages available for windows servers.
</p>
<p>
After you have installed your server software you can begin
installing CitrusDB. The main internal application is the largest
part of CitrusDB. It is built for use by customer service
representatives to handle customer service queries and sales,
billing staff to send bills and process payments, and by
administrators to activate new services, deactivate services, and
monitor customer service operations.
</p>
<p>
If you are simply trying out CitrusDB it can be installed on any
server you like. When using CitrusDB with real production data it
should be installed on a private LAN or on a well protected web
server with limited access by using firewalls and SSL, or other
comparable security measures to protect your customer data and
limit access to only you and your staff. Follow the steps below to
begin your installation.
</p>
</div>
<div id="outline-container-2.1" class="outline-3">
<h3 id="sec-2.1">2.1 Installing the Main Internal Application </h3>
<div id="text-2.1">
<ul>
<li>
Un-tar and un-gzip the citrus file wherever you want the
CitrusDB program to be located on your web server.
</li>
<li>
Create a MySQL database called "citrus" and import the citrus.sql
file into it. You can do this using a utility like phpMyAdmin or the
command line like the one shown here:
<pre class="example">
mysqladmin create citrus
mysql citrus < /path/to/citrusdb/citrus.sql
</pre>
</li>
<li>
Create a MySQL database user with access to the citrus database
you just created.
</li>
<li>
Edit the database configuration file: /citrusdb/application/config/database.php
</li>
<li>
Change the database hostname, to your server name, often this will
be the localhost it is all on one server. Enter your database
username and password that you just created before.
<pre class="example">
$db['default']['hostname']='localhost';
$db['default']['username']='username';
$db['default']['password']='password';
</pre>
<li>
Next edit the configuration file: /citrusdb/application/config/config.inc.php
</li>
<li>
Set the regular url and ssl url prefixes for your site. You should use the same
name for both the regular url and ssl url with the only difference being http or
https for the protocol. This will ensure the session cookie assigned during ssl
login is available to the regular http url as well.
<p>
You may use a self-signed certificate for this function as long as all the users
of the database have that SSL certificate installed into their browsers.
The CitrusDB project is an affiliate of
<a href="https://www.certs4less.com/affiliate/idevaffiliate.php?id=1035&url=3">Certs4Less</a>
where you can get an SSL certificate signed by a number of certificate authorities at different levels of authentication.
<pre class="example">
$config['base_url'] = "http://server.example.com/citrusdb/";
$config['ssl_base_url'] = "https://server.example.com/citrusdb/";
</pre>
</li>
<li>
Set the gpg command that will be used for encryption
of stored credit card data. In order to use gpg you must
generate a public and private keypair. It is probably a good
idea to generate a gpg keypair just for citrusdb to use. This
public key can then be used on the order side to store credit card
numbers before they are imported as well as storing cards
entered directly into citrusdb.
<p>
To generate a keypair run the command: gpg –gen-key
</p>
<p>
I recommend using the shortest recommended key length of 1024
bits since this key will be used over and over again, using the
shorter key length will make decryption faster. This is a trade
off of speed vs. strength. One could also use gpg with the
symmetric encryption option or any other encryption system that can
output an OpenPGP ascii armor message format. Symmetric
encryption could be significantly faster, however it will
require protection of the passphrase that is used when
encrypting the card data.
</p>
<p>
The example shown below stores the gpg key as the www-data user
in their home directory. This home directory was created for
the user that the web server is running as. This is the easiest way
to make sure that the web server running citrusdb has access to the keys
that it will use to encrypt and decrypt the card data. If the web
server where you run citrusdb is inside your network and
dedicated to your internal use this should not be
an issue. If you are unable
to do this, then you will need to modify the permissions of your
.gnupg folder and the keyrings inside of it to be readable by
everyone. This is less desireable as it may expose them to other
users of that system as well as cause permission problems in the
future if you edit keys.
</p>
<pre class="example">
$config['gpg_command'] = "/usr/bin/gpg --homedir /home/www-data/.gnupg
--armor --batch -e -r 'CitrusDB'";
</pre>
</li>
<li>
Set the gpg decrypt command that is used when decrypting the
cards for batch exports or when re-keying the data. The decrypt
command must include the –passphrase-fd 0 command because the
passphrase will be passed to gpg by citrus's decryption
function.
<pre class="example">
$config['gpg_decrypt'] = "/usr/bin/gpg --homedir /home/www-data/.gnupg
--passphrase-fd 0 --yes --no-tty --skip-verify --decrypt";
</pre>
</li>
<li>
Set the gpg sign command will be used by citrus to verify
the passphrase entered before creating a batch file.
<pre class="example">
$config['gpg_sign'] = "/usr/bin/gpg --homedir /home/www-data/.gnupg
--passphrase-fd 0 --yes --no-tty --clearsign -u 'CitrusDB'";
</pre>
</li>
<li>
If you would like to use an LDAP server to authenticate users
you can setup the ldap variables. Set the ldap<sub>enable</sub> variable
to TRUE and the other variables to correspond to your LDAP configuration.
You should make sure you have configured your ldap server to work
with ssl so that the data passed between the web server and the ldap
server is not able to be intercepted by using the ldaps protocol.
</li>
<li>
You will need to have the user configured inside of the citrus user
utilities to allow them to login with LDAP, but you can manage their
password using your LDAP system.
<pre class="example">
$config['ldap_enable'] = FALSE;
$config['ldap_host'] = 'ldaps://localhost';
$config['ldap_dn'] = 'ou=webapps,dc=localhost';
$config['ldap_protocol_version'] = 3;
$config['ldap_uid_field'] = 'uid';
</pre>
</li>
<li>
If you have an xmpp or jabber server for ticket notifications you can setup
those xmpp account variables to allow citrus to send ticket notifications
via xmpp instant messages.
<pre class="example">
$config['xmpp_server'] = "";
$config['xmpp_user'] = "";
$config['xmpp_password'] = "";
$config['xmpp_domain'] = "";
</pre>
</li>
<li>
A shipment tracking website URL like the one for US Postal, FedEx, or
UPS can be entered if you want to use the field asset
tracking number field when shipping field assets to customers.
<pre class="example">
$config['tracking_url'] = "http://trkcnfrm1.smi.usps.com/PTSInternetWeb/InterLabelInquiry.do?origTrackNum=";
</pre>
<li>
Scroll down to the Default Language section and variable to point to your local language
file. This language file is located in the /citrusdb/appliation/language folder and holds the values for all the text in
CitrusDB as well as the currency symbol used. Please note that
CitrusDB can only work with one currency.
<pre class="example">
$config['language'] = 'english';
</pre>
</li>
<li>
Scroll down to the Encryption Key section to change this to your own secret phrase.
<pre class="example">
$config['encryption_key']='youmustchangethis';
</pre>
</li>
</li>
<li>
add a cron job to run the statusupdate command. This command is run by calling:
<pre class="example">
php index.php command statusupdate
</pre>
on the command line from inside the citrusdb folder.
It should be run every night or after billing is done for the
day. This script will update the customer's account status and
create a file that can be used to activate and deactivate
customer services automatically. There is also a similar command called weekendupdate that can be run on weekends or holidays when you may not want to immediately turnoff or delete customer services.
</li>
<li>
Go to your web site address /citrusdb/index.php, you can log in
with username "admin", password "test" to start.
</li>
</ul>
<p>You have now finished the main installation of CitrusDB. It's a
good idea to login and change your admin password first. If you
are not going to install the customer account manager can skip to
Chapter 2 - Setup, to continue to setup of the internal CitrusDB
application.
</p></div>
</div>
<div id="outline-container-2.2" class="outline-3">
<h3 id="sec-2.2">2.2 Customer Self-Service Portal</h3>
<div id="text-2.2">
<p>CitrusDB 3.0 now includes a new online customer portal api to create a portal that will allow your customers to view information about their own account, request changes, and
make updates. It is recommended to put your portal web app on a seperate public web server and only have allow connections between it and your internal citrusdb server over https connections on port 443.
<p>
There is an example of a portal in the /citrusdb/portal folder. This is without any login that will automatically load the first example test account when their password is set to test. You may use these examples to make a portal that uses this API to meet your unique customer portal needs.
</p>
<p>
The portal also uses codeigniter configurations
customer system is configured similarly to the main
system by editing the config.inc.php file inside the
citrusdb/online/include folder. There are some additional
variables to configure for the online customer system.
</p>
<p>
The $payment_url variable should be set to whatever online
form or payment system you have such as authorize.net, paypal,
your own custom form etc.
</p>
<p>
The $notify_user variable holds a username from the internal
system that will be notified of new requests that customers make online.
</p></div>
</div>
<div id="outline-container-2.3" class="outline-3">
<h3 id="sec-2.3">2.3 Upgrading CitrusDB </h3>
<div id="text-2.3">
<p>When a there is a new installation or critical security update,
you will want to be able to upgrade your installation to the
latest release. To update from an older version to a newer one:
</p>
<ul>
<li>
Backup the php files by copying them to another location and
backup your citrus database by using a utility like mysqldump.
<pre class="example">
mysqldump –user <username> –password <passwd> db_name > backup.sql
</pre>
</li>
<li>
After you have backed up your current installation, replace the
old citrusdb files with the new ones from the package you downloaded
</li>
<li>
Edit the config.inc.php in /citrusdb/include with the database
and path information from your old config file.
</li>
<li>
To update your database schema from the old to the new you must run the update command from the command line. First you must cd into the folder that contains your citrusdb installation. Then run:
<pre class="example">
php index.php command update
</pre>
</li>
<li>
Your database has now been updated, and you are ready to use
your new version of CitrusDB.
</li>
<li>
If you are upgrading from version 1.x to 2.x you will need to
make sure you have setup the new gpg commands in the config file
and then run the encryptcards script to encrypt the cards in the database.
</li>
</ul>
</div>
</div>
</div>
<div id="outline-container-3" class="outline-2">
<h2 id="sec-3">3 Chapter 2: Setup </h2>
<div id="text-3">
</div>
<div id="outline-container-3.1" class="outline-3">
<h3 id="sec-3.1">3.1 Login </h3>
<div id="text-3.1">
<p>After you have installed CitrusDB the first thing you should do is
login with the default username (admin) and password (test) and
then go update the password to something new. To update the
password, click on the Tools icon, and then click on Change
Password. Enter a new password for the default admin user.
</p>
<p>
The login system will stop your login attempts from your IP
address if you fail to login with the correct username and
password after 5 tries in the last 24 hours. If this happens, your
IP address must be removed from the login_failures table by the
database administrator.
</p></div>
</div>
<div id="outline-container-3.2" class="outline-3">
<h3 id="sec-3.2">3.2 Organization Configuration </h3>
<div id="text-3.2">
<p>
The Organization Configuration section holds information about the
company or organization using CitrusDB. This should be the first
thing you configure when setting up CitrusDB. The information is
used in many places for invoices, billing, and customer messages.
</p>
<p>
The Billed By field holds the organization's brand name. If you
have more than one organization brand name you can add multiple
organization brands using the Add link to create more than one
organization listing. This is used to create bills under different
brand names and different credit card batches for those brands. If
your organization does not need multiple brands you can simply edit
the default configuration.
</p>
<p>
Enter the organization's name that will
appear on the bill in the Billed By field. Then the street, city,
state, zip, phone, and email information. The billing phone and
billing email will appear on the printed and emailed invoices.
</p>
<p>
Credit Card Export Variable Order is the order of the variables
that are exported in the credit card batch file for processing by
your credit card processing system. You can export a number
of different variables. All the available variables are listed at
the bottom of the organization screen. Please note that you need to
put the $ in front of the variable name so that they are evaluated
correctly. CitrusDB will insert the words "CREDIT" or "CHARGE" in quotes at the
beginning of the variables, depending on what kind of credit card
transaction this is. The recommended export format uses comma and quote
delimited items. You must keep the commas between the items and
quotes around them to make sure other systems can import the
information correctly.
</p>
<pre class="example">
"$mybilling_id","$invoice_number,"$billing_ccnum","$billing_ccexp","$abstotal"...
</pre>
<p>
Export File Prefix is is appended to the beginning of all credit
card batch files exported by citrus. If you have multiple
organizations exporting from the same citrus system, you can use
this file prefix name to identify which exported batches belong to
which organization.
</p>
<p>
Past Due Days are the number of days an account is past due before
the status is updated by the statusupdate script to one of the
three different past due status types: Past Due, Turned Off, or
Canceled.
Past Due accounts will be noted as past due and will be notified in
email by
the statusupdate script about their status. A Turned Off status will
cause the account to send a disable message to the account
activation system, which can then disable access to the account.
An account in a Turned Off status should be disabled and
non-working. The Canceled status is for accounts that have
been through the first two phases of being past due and have not
yet paid for services. Canceled will send a delete message to
the account activation system. The account should be removed
from your systems, and if you have a collections department or
processing system, can be forwarded to them for past due amount
recovery.
</p>
<p>
Carrier Dependent Past Due Days are for third party services that
have special requirements when they are turned off. They act the
same as normal Past Due Days however they have a Shutoff Notice
period in between being Past Due and having their service being
Turned Off. This shutoff notice is to notify the customer that
their service will be turned off and also to notify the billing
group that the service is in jeopardy of being shutoff. The
billing group will receive notifications when this service is to be
turned off or canceled, since they will need to be able to contact
the third party service carrier to handle type of cancel request.
</p>
<p>
The next fields are the four different kinds of invoice
notes that are printed at the bottom of the invoices according to
the account status. The Default Invoice Note is printed on an
account in good standing, usually this is a note thanking them for
using your services. The Past Due Invoice Note is printed on
invoices while an account is in the Past Due status. The Turned
Off Invoice Note is printed on invoices while an account is in the
Turned Off status. The Collections Invoice Note is printed on
invoices for accounts in the collections status. These messages
can be overridden by entering a custom message in the Notes field
on the customer's billing record.
</p>
<p>
The declined subject and message field hold the data used in the
email that is sent to customers when their credit card has been
declined. Here you should enter a message that will prompt them to
contact you and get their billing information up to date.
</p>
<p>
The last field is an invoice footer field that holds text that will be
placed at the bottom of every invoice.
</p>
<p>
After you have setup the organization information you are ready to save
your changes and continue setting up your CitrusDB system.
</p></div>
</div>
<div id="outline-container-3.3" class="outline-3">
<h3 id="sec-3.3">3.3 Settings </h3>
<div id="text-3.3">
<p>
The settings tool holds system wide settings for citrus.
</p>
<p>
At the top of the Settings screen you will see a
Citrus Database Version and Citrus Software Version. The database
version is the version of the SQL Schema that is being used. The
software version indicates the version of the software application
files. These two versions should be the same. If they are
different it may mean that you have not run the update script to
update your database to the correct version or that you are
running a Pre-release version of CitrusDB.
</p>
<p>
The Path to Credit Card File should be set to a file path on the
server to a folder that is outside the path of the web server and
other network processes. When credit card and account activation
data is created it will be saved to a new file inside this folder.
You can then write scripts that will automatically process new
files left in that folder, or download those files to process them
manually. You should make a new folder to store this data in, for
example, on a Unix system you can set this to something like
</p>
<pre class="example">
/var/billing
</pre>
<p>
and on a Windows system it can be set to a path such
as
</p>
<pre class="example">
C:\billing
</pre>
<p>
This will keep this data outside of the web server
path, but will still allow it to be accessed by 3rd party scripts
running on the server that can process this data automatically.
</p>
<p>
The Default Group is used by the support notes and privileges
system to allow notifications to certain users. Normally leaving
this as the default of "users" is recommended.
</p>
<p>
The Billing Group is a group that you will need to create if you
are using the carrier dependent services functions or if you are
using the Field Asset feature. The status
update script will send the billing group notes if a carrier
dependent service is in a bad billing status, like past due, turned
off, or canceled with fees owed. The field asset feature will send
a note to billing whenever a device is returned so that the billing
group knows the customer has returned a device and can take
measures necessary to adjust their bill.
</p>
<p>
The Shipping Group is a group that you will need to create if you
are going to use the Ship Field Asset feature. Ship Field Assets
lets you associate a field asset like a CPE or other device with
that customer's service. The shipping group will get a note when a
field asset is setup to be shipped.
</p>
<p>
The carrier dependent cancel url is for third party carrier
dependent services. This can link to an internal web form or other
form when a carrier dependent service is canceled to notify the
third party carrier that this service is to be canceled.
</p>
<p>
The Billing Date Rollover time should be set to the time of day
when new accounts created after this time will not be billed until
the next billing day. This is used to prevent new accounts from
being given the current billing date after the batch has already
been processed for the day. This time field is in 24 hour time format.
</p>
<p>
The Weekend indicators allow the billing system to automatically
skip certain days when assigning new billing dates to new
customers. This is especially usefull for billing around
weekends, so that a new customer's billing date does not fall on a
weekend. You can choose what days of the week you want to assign
as weekends here.
</p>
</div>
</div>
<div id="outline-container-3.4" class="outline-3">
<h3 id="sec-3.4">3.4 Users </h3>
<div id="text-3.4">
<p>
The Users Tool will allow you to add CitrusDB database users.
This is used to add your staff personnel that will be using the
database to access customer information and billing. The user
tool will show you a list of current users. In the default
installation there will be two users present. An admin user that
has all privileges to edit everything about the database, and an
online user that is used to demonstrate the online customer
account manager's message notification. If you have not yet done
so, you should change the password for both the Admin user and
Online Request user to something new.
</p>
<p>
To add a new user click Add New Database User. You will then be
presented with a form to fill out, including the user's real name,
their username, and their password. You will also choose their
tool privileges here. Admin privileges will allow access to add
new users, edit billing types, add new services, and add new
modules. The Manager privilege will allow access to the credit
card import/export features, invoices, payments, reports, and
account activation. All other users should have No selected for
both Admin and Manager privileges.
</p>
<p>
You can edit existing users by clicking the Edit link next to
their name. This will allow you to change their tool privileges,
their username, and their password. You can also delete a user by
clicking the Delete link next to their name. When you delete a
user or change their username, any notes they have made will
stay in the database under their old username. You will also need
to update any groups they are a part of to include their new username.
</p></div>
</div>
<div id="outline-container-3.5" class="outline-3">
<h3 id="sec-3.5">3.5 Groups </h3>
<div id="text-3.5">
<p>The Groups tool is used to assign users to different groups for
notification and permission purposes. By default all the users
who are added to the database are put in the "users" group. This
should probably not be changed, since it affects access to many
pieces of the system. You can add as many other groups as
necessary. For instance, if you have a group of people who perform
shipping duties, you might make a shipping group and assign them
to this group. When a particular piece of equipment is needed you
can send a note to the shipping group, which will notify all the
individuals in that group about your message. When someone in the
group marks the message finished, it will dissapear from view of
all the people in the group.
</p>
<p>
This is also where you will add the billing group you specified
in the settings tool if you are using the carrier dependent
service functions.
</p>
</div>
</div>
<div id="outline-container-3.6" class="outline-3">
<h3 id="sec-3.6">3.6 Billing Types </h3>
<div id="text-3.6">
<p>The Edit Billing Types tool will allow you to edit what billing
types are available in the customer's billing record. CitrusDB
comes with a number of billing types already created, so you may
not need to create more. In fact, it may be better to delete
those that you do not need, so they don't get in the way. There
are 6 methods of billing:
</p>
<ul>
<li>
creditcard: For billing via a credit card batch export.
</li>