RangerMSP Wiki - PSA software for MSPs and IT services providers - User contributions [en]

Videos

2010-05-24T14:24:38Z

Reno: /* Ticket Management */

For better playback, allow the videos to download before playing.
====Getting Started====
*[http://www.commitcrm.com/videos/commit_crm_getting_started_tutorial_video.htm Getting Started Tutorial] - '''Recommended!''' (15 min.)

====Installation Guides====
*[http://www.commitcrm.com/videos/web_interface_installation_video.htm Web Interface Installation] (6 min.)
*[http://www.commitcrm.com/videos/email_connector_setup_video.htm Email Connector Installation] (12 min.)
*[http://www.commitcrm.com/videos/commit_alert_server_setup_video.htm Alerts Server Installation] (8 min.)
*[http://www.commitcrm.com/videos/commitcrm_upgrades_video.htm Upgrading CommitCRM] (3 min.)

====Contracts & Billing====
*[http://www.commitcrm.com/videos/commit_contracts_introduction_video.htm Contracts Introduction] (4 min.)
*[http://www.commitcrm.com/videos/commit_contracts_global_tutorial_video.htm Global Contracts] (6 min.)
*[http://www.commitcrm.com/videos/commit_contracts_block_of_time_tutorial_video.htm Block Of Time Contracts] (7 min.)
*[http://www.commitcrm.com/videos/commit_contracts_block_of_money_tutorial_video.htm Block Of Money Contracts] (6 min.)
*[http://www.commitcrm.com/videos/commit_contracts_block_of_tickets_tutorial_video.htm Block Of Tickets Contracts] (5 min.)
*[http://www.commitcrm.com/videos/commit_contracts_management_tutorial_video.htm Contract Status and Billing] (7 min.)
*[http://www.commitcrm.com/videos/commit_contracts_contract_price_charges_video.htm Contract-Price Charges] (7 min.)
*[http://www.commitcrm.com/videos/commit_contracts_batch_copy_wizard_video.htm Renewing Recurring Contracts] (4 min.)

====Additional Tutorials====
*[http://www.commitcrm.com/videos/employee_web_interface_tutorial_video.htm Web Interface For Employees] (6 min.)
*[http://www.commitcrm.com/videos/commit_activity_templates_video.htm Managing Activity Templates] (7 min.)
*[http://www.commitcrm.com/videos/commit_report_designer_tutorial_video.htm Report Designer Tutorial] (7 min.)
*[http://commitcrm.com/videos/commitcrm_advanced_filter.htm Advanced Filter Tutorial] (5 min.) 

====Ticket Management====
*[http://www.commitcrm.com/videos/commitcrm_navigation_pane.htm Ticket Navigation Pane]
*[http://www.commitcrm.com/videos/commitcrm_tickets_inbox.htm Ticket Inbox]
*[http://www.commitcrm.com/videos/commitcrm_ticket_recipients_video/ Ticket Recipients]
*[http://www.commitcrm.com/videos/commitcrm_email_correspondences_video/ Automatic Ticket Email Correspondence Management]
*[http://www.commitcrm.com/videos/commitcrm_correspondence_settings_video/ Ticket Correspondence Settings]
*[http://www.commitcrm.com/videos/commitcrm_private_distribution_video/ Private Email Distribution]

 
=====Other Videos=====

'''Manage Accounts:''' Your IT service business Customers, Contacts and Leads
*[http://www.commitcrm.com/videos/new_account.htm See how to add a new Account in Commit™] (33 sec.)

'''Manage IT Service Contracts:''' Block of Time, Block of Money, Block of Tickets, Date Range etc.
*[http://www.commitcrm.com/videos/new_contract.htm See how to create a new Contract for an Account] (1 min, 16 sec.)

'''Manage Tickets''' and increase control over all the open issues, incidents and problems.
*[http://www.commitcrm.com/videos/new_ticket.htm See how to create a new Ticket in Commit™] (45 sec.)
*[http://www.commitcrm.com/videos/charging_ticket.htm See how to add Charges to an open Ticket in Commit™] (42 sec.)

'''Increase Productivity by Dispatching''' the right technician to the right call and by measuring the technician's productivity.

[[Category:Getting Started]]
*[http://www.commitcrm.com/videos/dispatching_ticket.htm See how to dispatch an open service ticket to a technician] (44 sec.)

'''Organize Your Price List''' for products and services.
*[http://www.commitcrm.com/videos/new_labor_item.htm See how to create a new item in Commit™] (41 sec.)

'''Increase Revenues by Easily Entering Charges''' for labor services, expenses, products and parts.
*[http://www.commitcrm.com/videos/new_part_charge.htm See how to create a new Charge in Commit™] (25 sec.)
*[http://www.commitcrm.com/videos/charging_ticket.htm See how to add charges to a service Ticket] (42 sec.)

'''Eliminate paperwork! Easily Manage All Documents''' including MS-Word®, MS-Excel®, presentations, emails, scanned documents etc.
*[http://www.commitcrm.com/videos/importing%20_documents.htm See how to import existing documents folders and link them to your accounts] (45 sec.)

__NOTOC__

[[Category:Setup]]

Videos

2010-05-21T13:53:29Z

Reno: /* Additional Tutorials */

For better playback, allow the videos to download before playing.
====Getting Started====
*[http://www.commitcrm.com/videos/commit_crm_getting_started_tutorial_video.htm Getting Started Tutorial] - '''Recommended!''' (15 min.)

====Installation Guides====
*[http://www.commitcrm.com/videos/web_interface_installation_video.htm Web Interface Installation] (6 min.)
*[http://www.commitcrm.com/videos/email_connector_setup_video.htm Email Connector Installation] (12 min.)
*[http://www.commitcrm.com/videos/commit_alert_server_setup_video.htm Alerts Server Installation] (8 min.)
*[http://www.commitcrm.com/videos/commitcrm_upgrades_video.htm Upgrading CommitCRM] (3 min.)

====Contracts & Billing====
*[http://www.commitcrm.com/videos/commit_contracts_introduction_video.htm Contracts Introduction] (4 min.)
*[http://www.commitcrm.com/videos/commit_contracts_global_tutorial_video.htm Global Contracts] (6 min.)
*[http://www.commitcrm.com/videos/commit_contracts_block_of_time_tutorial_video.htm Block Of Time Contracts] (7 min.)
*[http://www.commitcrm.com/videos/commit_contracts_block_of_money_tutorial_video.htm Block Of Money Contracts] (6 min.)
*[http://www.commitcrm.com/videos/commit_contracts_block_of_tickets_tutorial_video.htm Block Of Tickets Contracts] (5 min.)
*[http://www.commitcrm.com/videos/commit_contracts_management_tutorial_video.htm Contract Status and Billing] (7 min.)
*[http://www.commitcrm.com/videos/commit_contracts_contract_price_charges_video.htm Contract-Price Charges] (7 min.)
*[http://www.commitcrm.com/videos/commit_contracts_batch_copy_wizard_video.htm Renewing Recurring Contracts] (4 min.)

====Additional Tutorials====
*[http://www.commitcrm.com/videos/employee_web_interface_tutorial_video.htm Web Interface For Employees] (6 min.)
*[http://www.commitcrm.com/videos/commit_activity_templates_video.htm Managing Activity Templates] (7 min.)
*[http://www.commitcrm.com/videos/commit_report_designer_tutorial_video.htm Report Designer Tutorial] (7 min.)
*[http://commitcrm.com/videos/commitcrm_advanced_filter.htm Advanced Filter Tutorial] (5 min.) 

====Ticket Management====
*[http://www.commitcrm.com/videos/commitcrm_navigation_pane.htm Ticket Navigation Pane]
*[http://www.commitcrm.com/videos/commitcrm_tickets_inbox.htm Ticket Inbox]
*[http://www.commitcrm.com/videos/commitcrm_ticket_recipients_video/ Ticket Recipients]
*[http://www.commitcrm.com/videos/commitcrm_email_correspondences_video/ Automatic Ticket Email Correspondence Management]

 
=====Other Videos=====

'''Manage Accounts:''' Your IT service business Customers, Contacts and Leads
*[http://www.commitcrm.com/videos/new_account.htm See how to add a new Account in Commit™] (33 sec.)

'''Manage IT Service Contracts:''' Block of Time, Block of Money, Block of Tickets, Date Range etc.
*[http://www.commitcrm.com/videos/new_contract.htm See how to create a new Contract for an Account] (1 min, 16 sec.)

'''Manage Tickets''' and increase control over all the open issues, incidents and problems.
*[http://www.commitcrm.com/videos/new_ticket.htm See how to create a new Ticket in Commit™] (45 sec.)
*[http://www.commitcrm.com/videos/charging_ticket.htm See how to add Charges to an open Ticket in Commit™] (42 sec.)

'''Increase Productivity by Dispatching''' the right technician to the right call and by measuring the technician's productivity.

[[Category:Getting Started]]
*[http://www.commitcrm.com/videos/dispatching_ticket.htm See how to dispatch an open service ticket to a technician] (44 sec.)

'''Organize Your Price List''' for products and services.
*[http://www.commitcrm.com/videos/new_labor_item.htm See how to create a new item in Commit™] (41 sec.)

'''Increase Revenues by Easily Entering Charges''' for labor services, expenses, products and parts.
*[http://www.commitcrm.com/videos/new_part_charge.htm See how to create a new Charge in Commit™] (25 sec.)
*[http://www.commitcrm.com/videos/charging_ticket.htm See how to add charges to a service Ticket] (42 sec.)

'''Eliminate paperwork! Easily Manage All Documents''' including MS-Word®, MS-Excel®, presentations, emails, scanned documents etc.
*[http://www.commitcrm.com/videos/importing%20_documents.htm See how to import existing documents folders and link them to your accounts] (45 sec.)

__NOTOC__

[[Category:Setup]]

Videos

2010-05-21T13:52:49Z

Reno: /* Additional Tutorials */

For better playback, allow the videos to download before playing.
====Getting Started====
*[http://www.commitcrm.com/videos/commit_crm_getting_started_tutorial_video.htm Getting Started Tutorial] - '''Recommended!''' (15 min.)

====Installation Guides====
*[http://www.commitcrm.com/videos/web_interface_installation_video.htm Web Interface Installation] (6 min.)
*[http://www.commitcrm.com/videos/email_connector_setup_video.htm Email Connector Installation] (12 min.)
*[http://www.commitcrm.com/videos/commit_alert_server_setup_video.htm Alerts Server Installation] (8 min.)
*[http://www.commitcrm.com/videos/commitcrm_upgrades_video.htm Upgrading CommitCRM] (3 min.)

====Contracts & Billing====
*[http://www.commitcrm.com/videos/commit_contracts_introduction_video.htm Contracts Introduction] (4 min.)
*[http://www.commitcrm.com/videos/commit_contracts_global_tutorial_video.htm Global Contracts] (6 min.)
*[http://www.commitcrm.com/videos/commit_contracts_block_of_time_tutorial_video.htm Block Of Time Contracts] (7 min.)
*[http://www.commitcrm.com/videos/commit_contracts_block_of_money_tutorial_video.htm Block Of Money Contracts] (6 min.)
*[http://www.commitcrm.com/videos/commit_contracts_block_of_tickets_tutorial_video.htm Block Of Tickets Contracts] (5 min.)
*[http://www.commitcrm.com/videos/commit_contracts_management_tutorial_video.htm Contract Status and Billing] (7 min.)
*[http://www.commitcrm.com/videos/commit_contracts_contract_price_charges_video.htm Contract-Price Charges] (7 min.)
*[http://www.commitcrm.com/videos/commit_contracts_batch_copy_wizard_video.htm Renewing Recurring Contracts] (4 min.)

====Additional Tutorials====
*[http://www.commitcrm.com/videos/employee_web_interface_tutorial_video.htm Web Interface For Employees] (6 min.)
*[http://www.commitcrm.com/videos/commit_activity_templates_video.htm Managing Activity Templates] (7 min.)
*[http://www.commitcrm.com/videos/commit_report_designer_tutorial_video.htm Report Designer Tutorial] (7 min.)
*[http://commitcrm.com/videos/commitcrm_advanced_filter.htm Advanced Filter Tutorial] (5 min.)
 

====Ticket Management====
*[http://www.commitcrm.com/videos/commitcrm_navigation_pane.htm Ticket Navigation Pane]
*[http://www.commitcrm.com/videos/commitcrm_tickets_inbox.htm Ticket Inbox]
*[http://www.commitcrm.com/videos/commitcrm_ticket_recipients_video/ Ticket Recipients]
*[http://www.commitcrm.com/videos/commitcrm_email_correspondences_video/ Automatic Ticket Email Correspondence Management]

 
=====Other Videos=====

'''Manage Accounts:''' Your IT service business Customers, Contacts and Leads
*[http://www.commitcrm.com/videos/new_account.htm See how to add a new Account in Commit™] (33 sec.)

'''Manage IT Service Contracts:''' Block of Time, Block of Money, Block of Tickets, Date Range etc.
*[http://www.commitcrm.com/videos/new_contract.htm See how to create a new Contract for an Account] (1 min, 16 sec.)

'''Manage Tickets''' and increase control over all the open issues, incidents and problems.
*[http://www.commitcrm.com/videos/new_ticket.htm See how to create a new Ticket in Commit™] (45 sec.)
*[http://www.commitcrm.com/videos/charging_ticket.htm See how to add Charges to an open Ticket in Commit™] (42 sec.)

'''Increase Productivity by Dispatching''' the right technician to the right call and by measuring the technician's productivity.

[[Category:Getting Started]]
*[http://www.commitcrm.com/videos/dispatching_ticket.htm See how to dispatch an open service ticket to a technician] (44 sec.)

'''Organize Your Price List''' for products and services.
*[http://www.commitcrm.com/videos/new_labor_item.htm See how to create a new item in Commit™] (41 sec.)

'''Increase Revenues by Easily Entering Charges''' for labor services, expenses, products and parts.
*[http://www.commitcrm.com/videos/new_part_charge.htm See how to create a new Charge in Commit™] (25 sec.)
*[http://www.commitcrm.com/videos/charging_ticket.htm See how to add charges to a service Ticket] (42 sec.)

'''Eliminate paperwork! Easily Manage All Documents''' including MS-Word®, MS-Excel®, presentations, emails, scanned documents etc.
*[http://www.commitcrm.com/videos/importing%20_documents.htm See how to import existing documents folders and link them to your accounts] (45 sec.)

__NOTOC__

[[Category:Setup]]

Videos

2010-05-21T13:51:53Z

Reno: /* Ticket Management (Requires CommitCRM 5.3 or newer) */

For better playback, allow the videos to download before playing.
====Getting Started====
*[http://www.commitcrm.com/videos/commit_crm_getting_started_tutorial_video.htm Getting Started Tutorial] - '''Recommended!''' (15 min.)

====Installation Guides====
*[http://www.commitcrm.com/videos/web_interface_installation_video.htm Web Interface Installation] (6 min.)
*[http://www.commitcrm.com/videos/email_connector_setup_video.htm Email Connector Installation] (12 min.)
*[http://www.commitcrm.com/videos/commit_alert_server_setup_video.htm Alerts Server Installation] (8 min.)
*[http://www.commitcrm.com/videos/commitcrm_upgrades_video.htm Upgrading CommitCRM] (3 min.)

====Contracts & Billing====
*[http://www.commitcrm.com/videos/commit_contracts_introduction_video.htm Contracts Introduction] (4 min.)
*[http://www.commitcrm.com/videos/commit_contracts_global_tutorial_video.htm Global Contracts] (6 min.)
*[http://www.commitcrm.com/videos/commit_contracts_block_of_time_tutorial_video.htm Block Of Time Contracts] (7 min.)
*[http://www.commitcrm.com/videos/commit_contracts_block_of_money_tutorial_video.htm Block Of Money Contracts] (6 min.)
*[http://www.commitcrm.com/videos/commit_contracts_block_of_tickets_tutorial_video.htm Block Of Tickets Contracts] (5 min.)
*[http://www.commitcrm.com/videos/commit_contracts_management_tutorial_video.htm Contract Status and Billing] (7 min.)
*[http://www.commitcrm.com/videos/commit_contracts_contract_price_charges_video.htm Contract-Price Charges] (7 min.)
*[http://www.commitcrm.com/videos/commit_contracts_batch_copy_wizard_video.htm Renewing Recurring Contracts] (4 min.)

====Additional Tutorials====
*[http://www.commitcrm.com/videos/employee_web_interface_tutorial_video.htm Web Interface For Employees] (6 min.)
*[http://www.commitcrm.com/videos/commit_activity_templates_video.htm Managing Activity Templates] (7 min.)
*[http://www.commitcrm.com/videos/commit_report_designer_tutorial_video.htm Report Designer Tutorial] (7 min.)
*[http://commitcrm.com/videos/commitcrm_advanced_filter.htm Advanced Filter Tutorial] (5 min.)

 
====Ticket Management====
*[http://www.commitcrm.com/videos/commitcrm_navigation_pane.htm Ticket Navigation Pane]
*[http://www.commitcrm.com/videos/commitcrm_tickets_inbox.htm Ticket Inbox]
*[http://www.commitcrm.com/videos/commitcrm_ticket_recipients_video/ Ticket Recipients]
*[http://www.commitcrm.com/videos/commitcrm_email_correspondences_video/ Automatic Ticket Email Correspondence Management]

 
=====Other Videos=====

'''Manage Accounts:''' Your IT service business Customers, Contacts and Leads
*[http://www.commitcrm.com/videos/new_account.htm See how to add a new Account in Commit™] (33 sec.)

'''Manage IT Service Contracts:''' Block of Time, Block of Money, Block of Tickets, Date Range etc.
*[http://www.commitcrm.com/videos/new_contract.htm See how to create a new Contract for an Account] (1 min, 16 sec.)

'''Manage Tickets''' and increase control over all the open issues, incidents and problems.
*[http://www.commitcrm.com/videos/new_ticket.htm See how to create a new Ticket in Commit™] (45 sec.)
*[http://www.commitcrm.com/videos/charging_ticket.htm See how to add Charges to an open Ticket in Commit™] (42 sec.)

'''Increase Productivity by Dispatching''' the right technician to the right call and by measuring the technician's productivity.

[[Category:Getting Started]]
*[http://www.commitcrm.com/videos/dispatching_ticket.htm See how to dispatch an open service ticket to a technician] (44 sec.)

'''Organize Your Price List''' for products and services.
*[http://www.commitcrm.com/videos/new_labor_item.htm See how to create a new item in Commit™] (41 sec.)

'''Increase Revenues by Easily Entering Charges''' for labor services, expenses, products and parts.
*[http://www.commitcrm.com/videos/new_part_charge.htm See how to create a new Charge in Commit™] (25 sec.)
*[http://www.commitcrm.com/videos/charging_ticket.htm See how to add charges to a service Ticket] (42 sec.)

'''Eliminate paperwork! Easily Manage All Documents''' including MS-Word®, MS-Excel®, presentations, emails, scanned documents etc.
*[http://www.commitcrm.com/videos/importing%20_documents.htm See how to import existing documents folders and link them to your accounts] (45 sec.)

__NOTOC__

[[Category:Setup]]

Videos

2010-05-20T21:08:10Z

Reno: /* Ticket Management (Requires CommitCRM 5.3 or newer) */

For better playback, allow the videos to download before playing.
====Getting Started====
*[http://www.commitcrm.com/videos/commit_crm_getting_started_tutorial_video.htm Getting Started Tutorial] - '''Recommended!''' (15 min.)

====Installation Guides====
*[http://www.commitcrm.com/videos/web_interface_installation_video.htm Web Interface Installation] (6 min.)
*[http://www.commitcrm.com/videos/email_connector_setup_video.htm Email Connector Installation] (12 min.)
*[http://www.commitcrm.com/videos/commit_alert_server_setup_video.htm Alerts Server Installation] (8 min.)
*[http://www.commitcrm.com/videos/commitcrm_upgrades_video.htm Upgrading CommitCRM] (3 min.)

====Contracts & Billing====
*[http://www.commitcrm.com/videos/commit_contracts_introduction_video.htm Contracts Introduction] (4 min.)
*[http://www.commitcrm.com/videos/commit_contracts_global_tutorial_video.htm Global Contracts] (6 min.)
*[http://www.commitcrm.com/videos/commit_contracts_block_of_time_tutorial_video.htm Block Of Time Contracts] (7 min.)
*[http://www.commitcrm.com/videos/commit_contracts_block_of_money_tutorial_video.htm Block Of Money Contracts] (6 min.)
*[http://www.commitcrm.com/videos/commit_contracts_block_of_tickets_tutorial_video.htm Block Of Tickets Contracts] (5 min.)
*[http://www.commitcrm.com/videos/commit_contracts_management_tutorial_video.htm Contract Status and Billing] (7 min.)
*[http://www.commitcrm.com/videos/commit_contracts_contract_price_charges_video.htm Contract-Price Charges] (7 min.)
*[http://www.commitcrm.com/videos/commit_contracts_batch_copy_wizard_video.htm Renewing Recurring Contracts] (4 min.)

====Additional Tutorials====
*[http://www.commitcrm.com/videos/employee_web_interface_tutorial_video.htm Web Interface For Employees] (6 min.)
*[http://www.commitcrm.com/videos/commit_activity_templates_video.htm Managing Activity Templates] (7 min.)
*[http://www.commitcrm.com/videos/commit_report_designer_tutorial_video.htm Report Designer Tutorial] (7 min.)
*[http://commitcrm.com/videos/commitcrm_advanced_filter.htm Advanced Filter Tutorial] (5 min.)

 
====Ticket Management (Requires CommitCRM 5.3 or newer)====
*[http://www.commitcrm.com/videos/commitcrm_navigation_pane.htm Ticket Navigation Pane]
*[http://www.commitcrm.com/videos/commitcrm_tickets_inbox.htm Ticket Inbox]
*[http://www.commitcrm.com/videos/commitcrm_ticket_recipients_video/ Ticket Recipients]
*[http://www.commitcrm.com/videos/commitcrm_email_correspondences_video/ Automatic Ticket Email Correspondence Management]

 
=====Other Videos=====

'''Manage Accounts:''' Your IT service business Customers, Contacts and Leads
*[http://www.commitcrm.com/videos/new_account.htm See how to add a new Account in Commit™] (33 sec.)

'''Manage IT Service Contracts:''' Block of Time, Block of Money, Block of Tickets, Date Range etc.
*[http://www.commitcrm.com/videos/new_contract.htm See how to create a new Contract for an Account] (1 min, 16 sec.)

'''Manage Tickets''' and increase control over all the open issues, incidents and problems.
*[http://www.commitcrm.com/videos/new_ticket.htm See how to create a new Ticket in Commit™] (45 sec.)
*[http://www.commitcrm.com/videos/charging_ticket.htm See how to add Charges to an open Ticket in Commit™] (42 sec.)

'''Increase Productivity by Dispatching''' the right technician to the right call and by measuring the technician's productivity.

[[Category:Getting Started]]
*[http://www.commitcrm.com/videos/dispatching_ticket.htm See how to dispatch an open service ticket to a technician] (44 sec.)

'''Organize Your Price List''' for products and services.
*[http://www.commitcrm.com/videos/new_labor_item.htm See how to create a new item in Commit™] (41 sec.)

'''Increase Revenues by Easily Entering Charges''' for labor services, expenses, products and parts.
*[http://www.commitcrm.com/videos/new_part_charge.htm See how to create a new Charge in Commit™] (25 sec.)
*[http://www.commitcrm.com/videos/charging_ticket.htm See how to add charges to a service Ticket] (42 sec.)

'''Eliminate paperwork! Easily Manage All Documents''' including MS-Word®, MS-Excel®, presentations, emails, scanned documents etc.
*[http://www.commitcrm.com/videos/importing%20_documents.htm See how to import existing documents folders and link them to your accounts] (45 sec.)

__NOTOC__

[[Category:Setup]]

Videos

2010-05-20T21:07:44Z

Reno: /* Additional Tutorials */

For better playback, allow the videos to download before playing.
====Getting Started====
*[http://www.commitcrm.com/videos/commit_crm_getting_started_tutorial_video.htm Getting Started Tutorial] - '''Recommended!''' (15 min.)

====Installation Guides====
*[http://www.commitcrm.com/videos/web_interface_installation_video.htm Web Interface Installation] (6 min.)
*[http://www.commitcrm.com/videos/email_connector_setup_video.htm Email Connector Installation] (12 min.)
*[http://www.commitcrm.com/videos/commit_alert_server_setup_video.htm Alerts Server Installation] (8 min.)
*[http://www.commitcrm.com/videos/commitcrm_upgrades_video.htm Upgrading CommitCRM] (3 min.)

====Contracts & Billing====
*[http://www.commitcrm.com/videos/commit_contracts_introduction_video.htm Contracts Introduction] (4 min.)
*[http://www.commitcrm.com/videos/commit_contracts_global_tutorial_video.htm Global Contracts] (6 min.)
*[http://www.commitcrm.com/videos/commit_contracts_block_of_time_tutorial_video.htm Block Of Time Contracts] (7 min.)
*[http://www.commitcrm.com/videos/commit_contracts_block_of_money_tutorial_video.htm Block Of Money Contracts] (6 min.)
*[http://www.commitcrm.com/videos/commit_contracts_block_of_tickets_tutorial_video.htm Block Of Tickets Contracts] (5 min.)
*[http://www.commitcrm.com/videos/commit_contracts_management_tutorial_video.htm Contract Status and Billing] (7 min.)
*[http://www.commitcrm.com/videos/commit_contracts_contract_price_charges_video.htm Contract-Price Charges] (7 min.)
*[http://www.commitcrm.com/videos/commit_contracts_batch_copy_wizard_video.htm Renewing Recurring Contracts] (4 min.)

====Additional Tutorials====
*[http://www.commitcrm.com/videos/employee_web_interface_tutorial_video.htm Web Interface For Employees] (6 min.)
*[http://www.commitcrm.com/videos/commit_activity_templates_video.htm Managing Activity Templates] (7 min.)
*[http://www.commitcrm.com/videos/commit_report_designer_tutorial_video.htm Report Designer Tutorial] (7 min.)
*[http://commitcrm.com/videos/commitcrm_advanced_filter.htm Advanced Filter Tutorial] (5 min.)

 
====Ticket Management (Requires CommitCRM 5.3 or newer)====
*[http://www.commitcrm.com/videos/commitcrm_navigation_pane.htm Ticket Navigation Pane]]
*[http://www.commitcrm.com/videos/commitcrm_tickets_inbox.htm Ticket Inbox]]
*[http://www.commitcrm.com/videos/commitcrm_ticket_recipients_video/ Ticket Recipients]
*[http://www.commitcrm.com/videos/commitcrm_email_correspondences_video/ Automatic Ticket Email Correspondence Management]

 
=====Other Videos=====

'''Manage Accounts:''' Your IT service business Customers, Contacts and Leads
*[http://www.commitcrm.com/videos/new_account.htm See how to add a new Account in Commit™] (33 sec.)

'''Manage IT Service Contracts:''' Block of Time, Block of Money, Block of Tickets, Date Range etc.
*[http://www.commitcrm.com/videos/new_contract.htm See how to create a new Contract for an Account] (1 min, 16 sec.)

'''Manage Tickets''' and increase control over all the open issues, incidents and problems.
*[http://www.commitcrm.com/videos/new_ticket.htm See how to create a new Ticket in Commit™] (45 sec.)
*[http://www.commitcrm.com/videos/charging_ticket.htm See how to add Charges to an open Ticket in Commit™] (42 sec.)

'''Increase Productivity by Dispatching''' the right technician to the right call and by measuring the technician's productivity.

[[Category:Getting Started]]
*[http://www.commitcrm.com/videos/dispatching_ticket.htm See how to dispatch an open service ticket to a technician] (44 sec.)

'''Organize Your Price List''' for products and services.
*[http://www.commitcrm.com/videos/new_labor_item.htm See how to create a new item in Commit™] (41 sec.)

'''Increase Revenues by Easily Entering Charges''' for labor services, expenses, products and parts.
*[http://www.commitcrm.com/videos/new_part_charge.htm See how to create a new Charge in Commit™] (25 sec.)
*[http://www.commitcrm.com/videos/charging_ticket.htm See how to add charges to a service Ticket] (42 sec.)

'''Eliminate paperwork! Easily Manage All Documents''' including MS-Word®, MS-Excel®, presentations, emails, scanned documents etc.
*[http://www.commitcrm.com/videos/importing%20_documents.htm See how to import existing documents folders and link them to your accounts] (45 sec.)

__NOTOC__

[[Category:Setup]]

SQL Database Troubleshooting

2010-05-11T12:15:01Z

Reno: /* Adding Service Dependency Rules */

__TOC__

 
==Problem Description==
When setting up the Commit SQL Database (CSD), the client PCs running the CommitCRM client application cannot connect to the Commit SQL Database, and an error is displayed saying:

Procedure halted due to data server error. Verify server is operating and this computer has access to the server folder. (C:\Commit\DB)

 
[[File:Error.jpg]]

 

==Explanation==
This problem occurs when the client PCs try to connect to the Commit SQL Database, which is installed on your server, and it doesn’t “answer” to their connection requests.
By default, CommitCRM clients send a UDP broadcast message on the network, checking where the Commit SQL Database server is found; if found the server answers with the relevant information for the client to connect to it (IP, Port, etc.). This handshake process may require allowing UDP broadcasts inside you LAN. Usually this does not require any special setup; however, with some advanced network security settings it may be required.
It is also required that the Commit SQL Database, which runs on your server as a Windows service called Advantage Database Server, will be up and running and be allowed to communicate with your LAN.

 

==Troubleshooting Steps==
In order to assure the Commit SQL Database can communicate with the CommitCRM clients, we ask that you cover the following steps.

*'''Please remember to test the Commit SQL Database communications again after applying each step, and if the issue persists, then the next step should be applied.'''

===Advantage Server===
*Verfiy the Advantage Database Server service is started on your server. For installation instructions click [[Commit_SQL_Database_Installation_Guide|here]] or [[Commit_SQL_Database_for_Trial_Users|here]] if your are using a trial copy of CSD.

*'''Please restart all Commit services, and retest communications by loading a CommitCRM Client application from another computer.'''

===DEP – Data Execution Prevention===
*Please ensure that if using DEP on the server, where Commit SQL Database (aka, Advantage Database Server) is installed, it should be configured to allow data execution for '''ADS.exe''', by default located in the following folder '''C:\Program Files\Extended Systems\Advantage 9007\Server'''. This file is the Commit SQL Database / Advantage Database Server Windows service executable file and therefore should be allowed, or else DEP may isolate the CSD software from communicating with the CommitCRM client applications.

*'''Please restart the Advantage service & all Commit services, and retest communications by loading a CommitCRM Client application from another computer.'''

 

===Firewall - Windows or any other installed Firewall===
*Make sure that your software firewall allows the Advantage port through the firewall (Advantage prot information can be adjusted from '''Start Menu > Programs > Advantage Database Server 9.0 > Advantage Configuration Utility > Configuration Utility tab > Communications tab'''). Also, make sure that no special UDP restrictions are activated on the CommitCRM server.
*If advanced firewall restrictions are configured, please verify that an exception has been placed in the firewall, so that the software may communicate with the network, as well as allowing UDP traffic through the firewall.

*'''Please restart the Advantage service & all Commit services, and retest communications by loading a CommitCRM Client application from another computer.'''

 

===ADS.ini – Server Locator===
*The CommitCRM client's way of finding the Commit SQL Database Server fails. In order for the client to detect where the server is running it broadcasts a UDP message and asks for the server to answer. When the server answers the client knows the server IP and can communicate with it.
*On your server, you can run the Advantage Configuration Utility ('''Start Menu > Programs > Advantage Database Server 9.0 > Advantage Configuration Utility > Configuration Utility tab > Communications tab'''). Using it you can find the Port number which is used for communicating with the clients. When adjusting the CSD ports, you can use any port you like, as long as the port is not being used by any other software.

 
[[File:Communicationstab.jpg]]
 
 
As explained in the previous steps, you should make sure that the Windows firewall on each client on your LAN allows communication with the server for this port. Verifying this will allow communication between the CommitCRM client and Commit SQL Database on the server.
 
 
However, in some cases this is not enough. As explained above, a discovery process takes place when the client loads, trying to find the server... It is possible that your Windows firewall blocks this discovery process even if the port is allowed.
 
 
Therefore, in case you enabled the port on each client (using the firewall settings window) and CommitCRM client still doesn't load, you should continue with the following ('''do not continue with this before testing whether allowing the port has solved the issue'''):

Under the '''<server>\Commit\LastVer'''  folder, create a text file called '''ADS.INI'''
Open this file in Notepad and add the following settings:

'''[MYSERVER] LAN_IP=192.168.0.1 LAN_PORT=2001 ''' 
''IMPORTANT NOTES'':
*Replace '''MYSERVER''' with the name of '''YOUR server'''
*Replace the '''192.168.0.1''' IP address with the '''LOCAL IP address of your server'''.
*Replace the port number '''2001 '''to the one used for Commit SQL Database in your setup ('''this can be viewed by running Advantage Configuration Utility on your server, look for the port in use for your LAN''').

After adding the relevant settings, save the file and then try to run CommitCRM client.
This file tells the CommitCRM client what the server IP is and what port to use and therefore no discovery process is required, avoiding the broadcast stage.

Please remember that in case you ever change the IP of your server on your LAN, you should make sure to update this file again to reflect the change. This is why we usually recommend on allowing the broadcast rather than using this hard-coded method of communication; however, in some configurations it doesn’t work and using an ADS.ini file is mandatory.

*'''Please restart the Advantage service & all Commit services, and retest communications by loading a CommitCRM Client application from another computer.'''
 
 

===ADS.ini – Server Locator (Supplemental)===
*If the Ads.ini file does not correct the issue, then we suggest that '''changing the Server hostname reference''' in ADS.ini to the '''server IP address [192.168.x.x]''' will correct this behavior. (Remember to restart Advantage Service each time ADS.ini is adjusted)
For example:
'''[192.168.0.1] LAN_IP=192.168.0.1 LAN_PORT=2001 '''
''IMPORTANT NOTE:''
*Please replace the ServerName (between the brackets) with '''the servers IP adress''', as displayed in the example above.

*'''Please restart the Advantage service & all Commit services, and retest communications by loading a CommitCRM Client application from another computer.'''

 
====Important Note For Users that Use our ODBC API====
I some cases your system may still present an error message regarding failure of the Discovery process (Advantage Error 6320) when trying to access to the CommitCRM database using an ODBC connection, even after the ADS.ini file has resolved the issues with CommitCRM clients being able to discover the Advantage server. The following solution should resolve this issue as long as the following conditions are met:

* You use the Commit SQL Database (aka, Advantage Database Server on your server) and ODBC.

* The ADS.ini file succeeded in logging in the CommitCRM Software Applications (Clients).

* When using applications you developed with ODBC you receive a message regarding Database Discovery Failure (Error code 6320).

If all of the above prerequisites exist, you should copy the ADS.ini file you prepared from the CommitCRM server folder into the following folder on each the affected workstation:

* '''%Windir%\system32'''

This folder usually translates to: '''C:\Windows\system32'''

'''Note:''' To open these folders on your PC you can paste the paths listed above into a Windows Run dialog box, or into any Windows Explorer path.

 

==Recurring issues after Rebooting the CommitCRM Server Machine==
The CommitCRM database chooses its database mode upon the first concurrent connection to the system. If a client application, or Commit Addon Service (Such as '''CommmitWebInterface''' or '''CommitServer''')service is already loaded and connected to the server before the Advantage Database Server service finishes loading, then all subsequent connections will be rejected since the prior connection to the database would not allow the Advantage Database Server service full control over the database.

Typical characteristics of this type of problem are repeated manual attention needed to properly connect Advantage Database Server to CommitCRM after rebooting, and restarting the Advantage Database Server service.
To verify this is the issue, please follow these steps:
#Stop any '''Commit Services''' installed in the CommitCRM server.
#Verify no other computers are running CommitCRM.
#Restart the '''Advantage Database Server''' Service.
#Once the '''Advantage Database Server''' service has started, Try Logging in with one client on the '''server machine'''.
#Check the CommitCRM window title to see if '''SQL''' is printed next to your username.
#If successful, Start '''Commit Services'''.

If this process was successful, this is because the '''Commit Services loaded before Advantage Database Server did''', locking Advantage Database Server out of the CommitCRM database. To permanently resolve this behavior, manual rules will''' need to be created''' in order to ensure that The Commit Services '''do not try to load without Advantage Database Server being started'''.

 
===Adding Service Dependency Rules===
Now that CommitCRM depends on the Advantage Database Server Database service, the Commit Services (CommitWebInterface & CommitServer) also need the Advantage Database Server server to to be up before they try to load.
To set these services to be dependent on the Advantage Database Server Service, follow these steps:
# Backup your current registry settings.
# Run '''regedit''' to open your registry.
# Navigate to '''HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services''' and locate the '''CommitWebInterface/CommitServer''' services that you need to set a dependency for.
# Open the '''DependOnService''' key on the right side. If the selected service does not have a '''DependOnService''' key, then create one by right-clicking and selecting '''New > Multi-String Value'''.
# In the '''value''' field, enter '''Advantage'''.
# Click OK, close your registry and restart your machine.

 

==See Also==
*[[Commit_SQL_Database_Installation_Guide|Commit SQL Database Installation Guide]]
*[[Commit_SQL_Database_for_Trial_Users|Commit SQL Database for Trial Users]]
[[Category:Troubleshooting]]

Videos

2010-04-22T17:15:08Z

Reno: /* Additional Tutorials */

For better playback, allow the videos to download before playing.
====Getting Started====
*[http://www.commitcrm.com/videos/commit_crm_getting_started_tutorial_video.htm Getting Started Tutorial] - '''Recommended!''' (15 min.)

====Installation Guides====
*[http://www.commitcrm.com/videos/web_interface_installation_video.htm Web Interface Installation] (6 min.)
*[http://www.commitcrm.com/videos/email_connector_setup_video.htm Email Connector Installation] (12 min.)
*[http://www.commitcrm.com/videos/commit_alert_server_setup_video.htm Alerts Server Installation] (8 min.)
*[http://www.commitcrm.com/videos/commitcrm_upgrades_video.htm Upgrading CommitCRM] (3 min.)

====Contracts & Billing====
*[http://www.commitcrm.com/videos/commit_contracts_introduction_video.htm Contracts Introduction] (4 min.)
*[http://www.commitcrm.com/videos/commit_contracts_global_tutorial_video.htm Global Contracts] (6 min.)
*[http://www.commitcrm.com/videos/commit_contracts_block_of_time_tutorial_video.htm Block Of Time Contracts] (7 min.)
*[http://www.commitcrm.com/videos/commit_contracts_block_of_money_tutorial_video.htm Block Of Money Contracts] (6 min.)
*[http://www.commitcrm.com/videos/commit_contracts_block_of_tickets_tutorial_video.htm Block Of Tickets Contracts] (5 min.)
*[http://www.commitcrm.com/videos/commit_contracts_management_tutorial_video.htm Contract Status and Billing] (7 min.)
*[http://www.commitcrm.com/videos/commit_contracts_contract_price_charges_video.htm Contract-Price Charges] (7 min.)
*[http://www.commitcrm.com/videos/commit_contracts_batch_copy_wizard_video.htm Renewing Recurring Contracts] (4 min.)

====Additional Tutorials====
*[http://www.commitcrm.com/videos/employee_web_interface_tutorial_video.htm Web Interface For Employees] (6 min.)
*[http://www.commitcrm.com/videos/commit_activity_templates_video.htm Managing Activity Templates] (7 min.)
*[http://www.commitcrm.com/videos/commit_report_designer_tutorial_video.htm Report Designer Tutorial] (7 min.)
*[http://commitcrm.com/videos/commitcrm_advanced_filter.htm Advanced Filter Tutorial] (5 min.)

 
=====Other Videos=====

'''Manage Accounts:''' Your IT service business Customers, Contacts and Leads
*[http://www.commitcrm.com/videos/new_account.htm See how to add a new Account in Commit™] (33 sec.)

'''Manage IT Service Contracts:''' Block of Time, Block of Money, Block of Tickets, Date Range etc.
*[http://www.commitcrm.com/videos/new_contract.htm See how to create a new Contract for an Account] (1 min, 16 sec.)

'''Manage Tickets''' and increase control over all the open issues, incidents and problems.
*[http://www.commitcrm.com/videos/new_ticket.htm See how to create a new Ticket in Commit™] (45 sec.)
*[http://www.commitcrm.com/videos/charging_ticket.htm See how to add Charges to an open Ticket in Commit™] (42 sec.)

'''Increase Productivity by Dispatching''' the right technician to the right call and by measuring the technician's productivity.

[[Category:Getting Started]]
*[http://www.commitcrm.com/videos/dispatching_ticket.htm See how to dispatch an open service ticket to a technician] (44 sec.)

'''Organize Your Price List''' for products and services.
*[http://www.commitcrm.com/videos/new_labor_item.htm See how to create a new item in Commit™] (41 sec.)

'''Increase Revenues by Easily Entering Charges''' for labor services, expenses, products and parts.
*[http://www.commitcrm.com/videos/new_part_charge.htm See how to create a new Charge in Commit™] (25 sec.)
*[http://www.commitcrm.com/videos/charging_ticket.htm See how to add charges to a service Ticket] (42 sec.)

'''Eliminate paperwork! Easily Manage All Documents''' including MS-Word®, MS-Excel®, presentations, emails, scanned documents etc.
*[http://www.commitcrm.com/videos/importing%20_documents.htm See how to import existing documents folders and link them to your accounts] (45 sec.)

__NOTOC__

[[Category:Setup]]

API Developers Guide

2010-04-19T13:47:46Z

Reno: /* Installing ODBC Driver */

{{usermanuals}}

=Introduction=
CommitCRM provides various tools in order to read/add/update information in the CommitCRM
database. These tools include: Programming API and API by Email for updating the
database, and an ODBC Link for pulling information from the database.
The Commit API provides developers with a set of APIs which allow them to perform
database transactions in order to add and update records in the CommitCRM database. The
API can be used as a Programming API by embedding code which uses the API functions,
or as an API by Email which allows you to send XML formatted emails which will be
processed and executed.

__TOC__

*'''Programming API''' The Commit API provides developers with a set of API functions which can be used in VB, C++, Delphi and any other programming language that lets you use a standard Windows dll file. It provides the ability to create a connection to CommitCRM's database, add new records to the database and update them.

*'''API by Email''' The API by Email allows you to send XML formatted emails which contain database transactions. Commit Email Connector then pulls the incoming XML emails from your POP3 mail server, processes the email and performs the transactions in the XML transaction. XML formatted email gives you an API for the CommitCRM database, which allows you to perform many actions such as linking to external systems, receiving forms submitted from your web site, and more.

*'''ODBC Link''' While the API provides the means for adding and updating information in the database, you should use ODBC Link in order to read information from the database. CommitCRM uses an open database structure and allows other applications to access the database using ODBC (Open Data Base Connectivity) for '''read-only''' purposes. You can use ODBC Link in order to read data from the database and integrate it with an external system (i.e. Crystal reports, or any other application). You may also use the ODBC Link to read Database Record IDs and update existing records. This will be discussed later in this document.

=Glossary=
*'''Commit API (Application Programming Interface)''' - CommitCRM provides an API which allows you to add and update records in the CommitCRM database. The API includes a list of possible actions and parameters.

*'''ODBC Link (Open Data Base Connectivity)''' - ODBC is a function library which provides a common API for ODBC compliant databases. CommitCRM provides an open database and allows other applications to access the database using ODBC for '''read-only''' purposes.

*'''Record''' - Each entity in the CommitCRM database (such as Ticket, Account, Asset, Item, Appointment, Task, etc.) is considered a "record".

*'''Database fields''' - Each record contains a list of fields, each of which holds the record's data.

*'''Transaction''' – All additions or updates to record in the database are done by using a transaction. Each transaction includes the operation you wish to perform, the data type you wish to add/update and the additional parameters (database fields and their values).

*'''Transaction Parameters''' - Each transaction contains the parameters for performing the transaction: record type, list of database fields and a list of the values to be updated in these fields.

*'''External Application''' - This refers to the external program which integrates with CommitCRM in order to update the database. This name should be passed when performing updates to the database, and it will be saved in the CommitCRM record to indicate who performed the changes.

*'''Record ID (REC ID)''' - Each record in CommitCRM has a '''unique Record ID''' which is created when adding the record to the database. Every ID is 20 characters and should be transferred with the API transaction when you need to update an existing record.

=Using Commit API=
Commit API allows you to add and update records in the CommitCRM database, such as
Accounts, Tickets, Assets, Items, Appointments, Tasks and more.

The updates are performed using transactions, where each transaction includes the
operation you wish to perform, the data type you wish to add/update, and any additional
parameters (i.e. record type, database fields and their values).

Every record added to the system is assigned a unique Record ID (REC ID) which is the
database identifier for this record.

The Commit API allows you to perform the following operations.

*'''Add new records''' - if no Record ID is passed in the transaction, the API assumes that this is a new record, adds it to the system and creates a new Record ID for it.

*'''Update existing records''' - if the record ID is passed in the transaction, and the record exists, the system will update the record with the information in the transaction.

In both cases, the system will try to set default values for fields which do not exist in the
incoming transaction. If it fails, the action will fail with an error.

Note that in order to '''read data''' from the CommitCRM database, you should use the ODBC
Link, which provides a read-only link for the CommitCRM database. See more details in
[[#Retrieving data using ODBC|Retrieving data using ODBC]].

==Workflow==
Following is a sample work-flow, which demonstrates the process of adding a new Account, and then adding a new Ticket to this Account, using the Commit API.

Note that the API can return two parameters to the External Application:
#The Commit REC ID - when adding new records to the database, this will contains the new record ID.
#The ExternalTransactionID (relevant for XML transaction only) - In case the external application passes a parameter to be returned with the response, the ExternalTransactionID will be returned as-is to in the response.

The External Application should keep the REC ID which is returned from the API response. This allows you to later update the existing records with new data or add records related to it (such as opening a Ticket under the Account).

[[File:flow.gif|center]]

==Updating existing records==
In order to update an already existing record in the database (e.g. add a Ticket to an
Account, update an Account's phone number, add a new Charge to an existing Ticket,
etc.), you should pass the record's unique identifier to the API so it will update the
existing record rather than create a new Account. The record's unique identifier is
referred to as the Record ID (REC ID).

The Record ID can be obtained in the following ways:
#'''API Response''' (as in the flow above) - You can extract the newly created Record ID from the Email Response when adding new records with the API. This requires the developer to process the API responses, and extract the returning REC ID for each newly added record.
#'''ODBC Link''' - Use the ODBC Link to find relevant records (Accounts, Tickets, etc.), and read all information from the database, including the unique Record ID.
#'''Manually''' - from the Account's Notes tab, at the bottom, right-click the REC ID field and copy it.

Once you have obtained the Record ID you can pass the Record ID as a parameter for the
API and update this record.

=Programming API=
The Programming API allows you access the CommitCRM database and perform transactions
from within a program (using various programming language). This means you can embed
code which accesses the CommitCRM database from within your own application, and add
your own functionality which updates the database.

The programming API executes database transactions. Each transaction uses API methods
provides by the API dll file which is located in the CommitCRM installation. Both the
Programming API and the API by Email use the same dll for performing the transactions.

Note that the API provides the tools needed for adding/updating information in the
database. In order to retrieve data, you should use the ODBC link which allows you to
connect to the database and retrieve data directly from the tables. You can read more
about it in the [[Commit_API_Developers_Guide#ODBC_Data_Retrieval|ODBC Data Retrieval]] section.

You can find more information and samples in the [[API Code Samples]] section.

=API by Email (XML transaction)=
The API by Email operates under the Commit Email Connector module, which
automatically processes incoming emails arriving at a defined public email address. The
Email may contain XML formatted messages which contain API transactions, and provides
a full API to CommitCRM.

The Email Connector pulls incoming emails from your POP3 mail server, and processes the
email. When an email containing XML formatted message is detected, the system analyzes
the XML content of the email and performs the transactions written in the XML. You may
set the Email Connector to send automatic replies in response to XML formatted email.

The API by Email executes database transactions. Each transaction uses API methods
provided by the API dll file which is located in the CommitCRM installation. Both the
Programming API and the API by Email use the same dll for performing the transactions.

Note that the API provides the tools for adding/updating information in the database. In
order to retrieve data, you should use the ODBC link which allows you to connect to the
database and retrieve data directly from the tables. You can read more about it in the
[[Commit_API_Developers_Guide#ODBC_Data_Retrieval|ODBC Data Retrieval]] section.

You can find more information and samples in [[API Code Samples#XML samples|XML samples]].

=ODBC Data Retrieval=
CommitCRM uses an open database and allows other applications to access it using ODBC
(Open Data Base Connectivity) for '''read-only''' purposes. While the API provides the means
for adding and updating information in the database, it is preferred to use ODBC to read
information from the database.

You can use ODBC Link to read data from the database and integrate it with an external
system (i.e. Crystal reports, or any other application). You may also use the ODBC Link in
order to read the Database Record ID and update existing records (see [[Commit_API_Developers_Guide#Updating_existing_records|Updating existing records]]).

'''Activation Notes:'''

*The ODBC drivers are well tested and work well, however, please note that the Commit Support team doesn't provide "pure ODBC" support.

*NEVER use ODBC to modify or delete data; use it for READ purposes only. Modifying data should be done using the Commit API.

*The ODBC Link can be used with your installed version of CommitCRM, and only requires installing an external driver. Before working with the API we recommend that you '''backup the database'''.

Below are the database table names and their meaning:
{| class="wikitable"
|-
! '''CommitCRM Record'''
! '''Database Table Name'''
|-
| Accounts
| Cards
|-
| Tickets
| Tickets
|-
| Charges
| Slips
|-
| Assets
| Assets
|-
| Appointments
| Events
|-
| Tasks
| Events
|-
| History Notes
| NoteBook
|-
| Opportunities
| Opps
|-
| Documents
| Docs
|-
| Knowledge Base
| KBArticles
|}

For the database fields list, please refer to [[Commit_API_Developers_Guide#API_Reference_Manual|API Reference Manual]] section.
You can find detailed instructions for using the ODBC Link in the [[Commit_API_Developers_Guide#Installing_ODBC_Driver|Installing ODBC Driver]] section.

==Installing ODBC Driver==
'''Product Overview''' 
The Advantage ODBC Driver is an ODBC version 3 driver based on the Advantage Client Engine that provides SQL access to the Advantage Database Server. The driver provides
full support for the "Minimum" ODBC SQL grammar specification, as well as many functions
included in the "Core" and "Extended" grammar specifications. When used with the
Advantage Database Server, ODBC users can have the
application stability, performance and reduced network traffic benefits of client/server
architecture.

'''Installation on Windows''' 
Like other ODBC drivers, the Advantage ODBC Driver is installed and managed using the
ODBC Administrator Utility. This utility works with the ODBC Driver Manager to configure
ODBC data sources. At runtime, the ODBC Driver Manager works with available drivers and
their configured data sources. If you have previously installed ODBC drivers, the ODBC Administrator may already be installed on your workstation. The icon for the Administrator is usually found in the Control Panel.

To install the Advantage ODBC Driver:
#Download the ODBC driver version that corresponds with your Advantage SQL Database Server version from the following links: (The Advantage Version number can be found in the [[Media:ADS_Version.jpg|Advantage Configuration Utility]] located on the CommitCRM Server) '''[http://www.commitcrm.com/downloads/commit-odbc-9-0-0-7.exe ODBC Driver Version 9.0] [http://www.commitcrm.com/downloads/commit-odbc-8-1-0-26.exe ODBC Driver Version 8.1] (**Also for systems that do not use the Commit SQL Database) '''
#Run the Setup program.
#Proceed through the setup windows to complete installation.
'''**DISCLAIMER: Using the ODBC connector without the Commit SQL Database is not recommended, since the chances for Database Corruption would be elevated.'''

'''Data Source Setup for Windows''' 
Once the Advantage ODBC Driver is installed, a data source needs to be configured to use
the Advantage ODBC Driver. The data source is an entry in the Windows Registry. When a
data source is defined for the Advantage Driver, all information specific to the Advantage
Driver and database files is stored under the Data Source entry in the Windows 95/98/ME/
NT/2000/2003/XP Registry. 
The database files and indexes must be stored on your file server, and the Advantage
Database Server must be loaded in order to access the files.

The Data Source settings may be modified at any time. Using the ODBC Administrator, you
may modify the Data Source and Option settings.
For specific information about the screen fields see the Data Source Setup Screen.

'''To Setup the Data Source:'''
#From the ODBC Administrator, click Add.
#Highlight the Advantage SQL ODBC line, and click OK.
#Type a unique data source name. For example, type AdvData. This name is used by applications to reference the data source.
#Specify the database or data dictionary path. Type a valid path name to a mapped drive on the server where the Advantage Database Server is installed or the path and file name of your Advantage Data Dictionary. Click Browse to select a database path or check the Data Dictionary check box and then browse to select a data dictionary file. Note Multiple Advantage data sources may need to be defined for your environment. If different settings are needed for ODBC connections in one application, separate data sources may be required.
#Review the options and change them to your desired setup.
#Once the Options are reviewed and/or altered, click OK to exit and save the settings. The new data source is displayed.
#Click Close to exit the ODBC Administrator.

'''ODBC Data Source Entries for Windows''' 
In Microsoft Windows, the entries are registry settings found on HKEY_CURRENT_USER\Software\ODBC\ODBC.INI\ (your unique data source name) or HKEY_LOCAL_MACHINE\Software\ODBC\ODBC.INI (your unique data source name). Unless specified otherwise, all registry entries can be setup by the Advantage ODBC Driver setup utility. See Data Source Setup for Windows and Data Source Setup Screen for more information. ODBC Data Source Keys.

'''ODBC Data Source Keys''' 
The following ODBC registry is '''required''' for the driver to load:
{| class="wikitable"
|-
! '''Registry Entry'''
! '''Comments'''
|-
| DataDirectory=data path
| 'data path' should be a valid path name for files locations (e.g., x:\data). This path is used to automatically select all tables in the specified directory.
|-
| DefaultType=Advantage
| Sets a certain type of database files to use Advantageproprietary ADT/ADI/ADM files.
|-
| ServerTypes=3
| Allows the Driver to use the remote or local server
|}

The following ODBC registry keys are '''optional''':

{| class="wikitable"
|-
! '''Registry Entry'''
! '''Comments'''
|-
| AdvantageLocking=ON \ OFF
| The default is ON to use the Advantage proprietary locking.
|-
| CharSet=OEM \ ANSI
| The default character collation setting is ANSI. If OEM is specified, Language must be indicated as well.
|-
| Language=USA
| Used if CharSet=OEM.
|-
| Description=String
| This is provided for easier administration.
|-
| Locking=RECORD \ FILE
| Indicates whether updates lock the entire file or the individual records that are updated. The default is RECORD.
|-
| MaxTableCloseCache=n
| N is the number of tables to hold in cache when cursors are opened and closed. The default is 25.
|-
| MemoBlockSize=n
| N is the size of the Advantage memo blocks in tables that are created by the ODBC driver. The default value is 8 for Advantage proprietary table (ADT/ADM).
|-
| Rows=TRUE \ FALSE
| Select whether deleted rows are displayed. If True, deleted rows are displayed. The default is False.
|-
| TrimTrailingSpaces=TRUE \ FALSE
| The default is False. If True is specified, trailing spaces in character fields will be removed prior to returning the values to the application.
|}

==Troubleshooting ODBC in 64 Bit Operating Systems==
The Commit ODBC drivers are mainly distributed for 32-bit operating systems; however, the same drivers are supported on the 64-bit operating systems (I.e. Windows 7 x64), and can be used to retrieve data from the CommitCRM database.

 
===Configuring Data Source in 64-Bit Systems===
When installing the ODBC drivers on 64-bit operating systems, the ODBC drivers may not be displayed in the default ODBC manager in windows control panel. In order to view the 32-bit ODBC manager in a 64-bit operating system, you’ll need to browse to '''%windir%\SysWOW64\odbcad32.exe''' and run the 32 bit ODBC Administrator manually. Once the data source has been configured there, you should be able to select the data source in your 3rd party ODBC programs.

 
=Samples=
The Commit API allows you to add/update the following entities:
*Accounts
*Assets
*Tickets
*Charges
*Appointments
*Tasks
*History Notes
*Opportunities
*Documents
*Knowledge Base Articles

Each API method requires a list of parameters which contain the field names and their values. The field names are the Database field names. You can see each field's name within the application (so you can verify which field you are about to update), by right-clicking the field and selecting Field Settings > Advanced Tab > view the Tech. Rec ID field.

You can view the complete list of database fields in the [[Commit_API_Developers_Guide#API_Reference_Manual|API Reference Manual]] above.

Following are samples for using the API by Email and the Programming API. The samples are basic and provide an easy starting point.

See [[API Code Samples]].

=API Reference Manual=

The API allows you to add/update the following entities:
*Accounts
*Assets
*Tickets
*Charges (and Contract-price Charges)
*Appointments
*Tasks
*History Notes
*Opportunities
*Documents
*Knowledge Base Articles

You can find a detailed listing of the database fields in the [[API Reference Manual]].

=See Also=
*[[API Code Samples]]
*[[API Reference Manual]]
*[[Email Connector|Commit Email Connector]]
*[[API by Email and MSP Integration]]
*[[MSP Integration Setup]]
*[http://www.commitcrm.com/sql_database_server.htm Commit SQL Database (CSD)]
*[[Commit SQL Database Installation Guide | Commit SQL Database (CSD) Installation Guide]]

[[Category:User Manuals]]
[[Category:Integration]]

API Developers Guide

2010-04-19T13:45:17Z

Reno: /* Installing ODBC Driver */

{{usermanuals}}

=Introduction=
CommitCRM provides various tools in order to read/add/update information in the CommitCRM
database. These tools include: Programming API and API by Email for updating the
database, and an ODBC Link for pulling information from the database.
The Commit API provides developers with a set of APIs which allow them to perform
database transactions in order to add and update records in the CommitCRM database. The
API can be used as a Programming API by embedding code which uses the API functions,
or as an API by Email which allows you to send XML formatted emails which will be
processed and executed.

__TOC__

*'''Programming API''' The Commit API provides developers with a set of API functions which can be used in VB, C++, Delphi and any other programming language that lets you use a standard Windows dll file. It provides the ability to create a connection to CommitCRM's database, add new records to the database and update them.

*'''API by Email''' The API by Email allows you to send XML formatted emails which contain database transactions. Commit Email Connector then pulls the incoming XML emails from your POP3 mail server, processes the email and performs the transactions in the XML transaction. XML formatted email gives you an API for the CommitCRM database, which allows you to perform many actions such as linking to external systems, receiving forms submitted from your web site, and more.

*'''ODBC Link''' While the API provides the means for adding and updating information in the database, you should use ODBC Link in order to read information from the database. CommitCRM uses an open database structure and allows other applications to access the database using ODBC (Open Data Base Connectivity) for '''read-only''' purposes. You can use ODBC Link in order to read data from the database and integrate it with an external system (i.e. Crystal reports, or any other application). You may also use the ODBC Link to read Database Record IDs and update existing records. This will be discussed later in this document.

=Glossary=
*'''Commit API (Application Programming Interface)''' - CommitCRM provides an API which allows you to add and update records in the CommitCRM database. The API includes a list of possible actions and parameters.

*'''ODBC Link (Open Data Base Connectivity)''' - ODBC is a function library which provides a common API for ODBC compliant databases. CommitCRM provides an open database and allows other applications to access the database using ODBC for '''read-only''' purposes.

*'''Record''' - Each entity in the CommitCRM database (such as Ticket, Account, Asset, Item, Appointment, Task, etc.) is considered a "record".

*'''Database fields''' - Each record contains a list of fields, each of which holds the record's data.

*'''Transaction''' – All additions or updates to record in the database are done by using a transaction. Each transaction includes the operation you wish to perform, the data type you wish to add/update and the additional parameters (database fields and their values).

*'''Transaction Parameters''' - Each transaction contains the parameters for performing the transaction: record type, list of database fields and a list of the values to be updated in these fields.

*'''External Application''' - This refers to the external program which integrates with CommitCRM in order to update the database. This name should be passed when performing updates to the database, and it will be saved in the CommitCRM record to indicate who performed the changes.

*'''Record ID (REC ID)''' - Each record in CommitCRM has a '''unique Record ID''' which is created when adding the record to the database. Every ID is 20 characters and should be transferred with the API transaction when you need to update an existing record.

=Using Commit API=
Commit API allows you to add and update records in the CommitCRM database, such as
Accounts, Tickets, Assets, Items, Appointments, Tasks and more.

The updates are performed using transactions, where each transaction includes the
operation you wish to perform, the data type you wish to add/update, and any additional
parameters (i.e. record type, database fields and their values).

Every record added to the system is assigned a unique Record ID (REC ID) which is the
database identifier for this record.

The Commit API allows you to perform the following operations.

*'''Add new records''' - if no Record ID is passed in the transaction, the API assumes that this is a new record, adds it to the system and creates a new Record ID for it.

*'''Update existing records''' - if the record ID is passed in the transaction, and the record exists, the system will update the record with the information in the transaction.

In both cases, the system will try to set default values for fields which do not exist in the
incoming transaction. If it fails, the action will fail with an error.

Note that in order to '''read data''' from the CommitCRM database, you should use the ODBC
Link, which provides a read-only link for the CommitCRM database. See more details in
[[#Retrieving data using ODBC|Retrieving data using ODBC]].

==Workflow==
Following is a sample work-flow, which demonstrates the process of adding a new Account, and then adding a new Ticket to this Account, using the Commit API.

Note that the API can return two parameters to the External Application:
#The Commit REC ID - when adding new records to the database, this will contains the new record ID.
#The ExternalTransactionID (relevant for XML transaction only) - In case the external application passes a parameter to be returned with the response, the ExternalTransactionID will be returned as-is to in the response.

The External Application should keep the REC ID which is returned from the API response. This allows you to later update the existing records with new data or add records related to it (such as opening a Ticket under the Account).

[[File:flow.gif|center]]

==Updating existing records==
In order to update an already existing record in the database (e.g. add a Ticket to an
Account, update an Account's phone number, add a new Charge to an existing Ticket,
etc.), you should pass the record's unique identifier to the API so it will update the
existing record rather than create a new Account. The record's unique identifier is
referred to as the Record ID (REC ID).

The Record ID can be obtained in the following ways:
#'''API Response''' (as in the flow above) - You can extract the newly created Record ID from the Email Response when adding new records with the API. This requires the developer to process the API responses, and extract the returning REC ID for each newly added record.
#'''ODBC Link''' - Use the ODBC Link to find relevant records (Accounts, Tickets, etc.), and read all information from the database, including the unique Record ID.
#'''Manually''' - from the Account's Notes tab, at the bottom, right-click the REC ID field and copy it.

Once you have obtained the Record ID you can pass the Record ID as a parameter for the
API and update this record.

=Programming API=
The Programming API allows you access the CommitCRM database and perform transactions
from within a program (using various programming language). This means you can embed
code which accesses the CommitCRM database from within your own application, and add
your own functionality which updates the database.

The programming API executes database transactions. Each transaction uses API methods
provides by the API dll file which is located in the CommitCRM installation. Both the
Programming API and the API by Email use the same dll for performing the transactions.

Note that the API provides the tools needed for adding/updating information in the
database. In order to retrieve data, you should use the ODBC link which allows you to
connect to the database and retrieve data directly from the tables. You can read more
about it in the [[Commit_API_Developers_Guide#ODBC_Data_Retrieval|ODBC Data Retrieval]] section.

You can find more information and samples in the [[API Code Samples]] section.

=API by Email (XML transaction)=
The API by Email operates under the Commit Email Connector module, which
automatically processes incoming emails arriving at a defined public email address. The
Email may contain XML formatted messages which contain API transactions, and provides
a full API to CommitCRM.

The Email Connector pulls incoming emails from your POP3 mail server, and processes the
email. When an email containing XML formatted message is detected, the system analyzes
the XML content of the email and performs the transactions written in the XML. You may
set the Email Connector to send automatic replies in response to XML formatted email.

The API by Email executes database transactions. Each transaction uses API methods
provided by the API dll file which is located in the CommitCRM installation. Both the
Programming API and the API by Email use the same dll for performing the transactions.

Note that the API provides the tools for adding/updating information in the database. In
order to retrieve data, you should use the ODBC link which allows you to connect to the
database and retrieve data directly from the tables. You can read more about it in the
[[Commit_API_Developers_Guide#ODBC_Data_Retrieval|ODBC Data Retrieval]] section.

You can find more information and samples in [[API Code Samples#XML samples|XML samples]].

=ODBC Data Retrieval=
CommitCRM uses an open database and allows other applications to access it using ODBC
(Open Data Base Connectivity) for '''read-only''' purposes. While the API provides the means
for adding and updating information in the database, it is preferred to use ODBC to read
information from the database.

You can use ODBC Link to read data from the database and integrate it with an external
system (i.e. Crystal reports, or any other application). You may also use the ODBC Link in
order to read the Database Record ID and update existing records (see [[Commit_API_Developers_Guide#Updating_existing_records|Updating existing records]]).

'''Activation Notes:'''

*The ODBC drivers are well tested and work well, however, please note that the Commit Support team doesn't provide "pure ODBC" support.

*NEVER use ODBC to modify or delete data; use it for READ purposes only. Modifying data should be done using the Commit API.

*The ODBC Link can be used with your installed version of CommitCRM, and only requires installing an external driver. Before working with the API we recommend that you '''backup the database'''.

Below are the database table names and their meaning:
{| class="wikitable"
|-
! '''CommitCRM Record'''
! '''Database Table Name'''
|-
| Accounts
| Cards
|-
| Tickets
| Tickets
|-
| Charges
| Slips
|-
| Assets
| Assets
|-
| Appointments
| Events
|-
| Tasks
| Events
|-
| History Notes
| NoteBook
|-
| Opportunities
| Opps
|-
| Documents
| Docs
|-
| Knowledge Base
| KBArticles
|}

For the database fields list, please refer to [[Commit_API_Developers_Guide#API_Reference_Manual|API Reference Manual]] section.
You can find detailed instructions for using the ODBC Link in the [[Commit_API_Developers_Guide#Installing_ODBC_Driver|Installing ODBC Driver]] section.

==Installing ODBC Driver==
'''Product Overview''' 
The Advantage ODBC Driver is an ODBC version 3 driver based on the Advantage Client Engine that provides SQL access to the Advantage Database Server. The driver provides
full support for the "Minimum" ODBC SQL grammar specification, as well as many functions
included in the "Core" and "Extended" grammar specifications. When used with the
Advantage Database Server, ODBC users can have the
application stability, performance and reduced network traffic benefits of client/server
architecture.

'''Installation on Windows''' 
Like other ODBC drivers, the Advantage ODBC Driver is installed and managed using the
ODBC Administrator Utility. This utility works with the ODBC Driver Manager to configure
ODBC data sources. At runtime, the ODBC Driver Manager works with available drivers and
their configured data sources. If you have previously installed ODBC drivers, the ODBC Administrator may already be installed on your workstation. The icon for the Administrator is usually found in the Control Panel.

To install the Advantage ODBC Driver:
#Download the ODBC driver version that corresponds with your Advantage SQL Database Server version from the following links: (The Advantage Version number can be found in the [[Media:ADS_Version.jpg|Advantage Configuration Utility]] located on the CommitCRM Server) '''[http://www.commitcrm.com/downloads/commit-odbc-9-0-0-7.exe ODBC Driver Version 9.0] [http://www.commitcrm.com/downloads/commit-odbc-8-1-0-26.exe ODBC Driver Version 8.1] (Also for systems that do not use the Commit SQL Database) '''
#Run the Setup program.
#Proceed through the setup windows to complete installation.

'''Data Source Setup for Windows''' 
Once the Advantage ODBC Driver is installed, a data source needs to be configured to use
the Advantage ODBC Driver. The data source is an entry in the Windows Registry. When a
data source is defined for the Advantage Driver, all information specific to the Advantage
Driver and database files is stored under the Data Source entry in the Windows 95/98/ME/
NT/2000/2003/XP Registry. 
The database files and indexes must be stored on your file server, and the Advantage
Database Server must be loaded in order to access the files.

The Data Source settings may be modified at any time. Using the ODBC Administrator, you
may modify the Data Source and Option settings.
For specific information about the screen fields see the Data Source Setup Screen.

'''To Setup the Data Source:'''
#From the ODBC Administrator, click Add.
#Highlight the Advantage SQL ODBC line, and click OK.
#Type a unique data source name. For example, type AdvData. This name is used by applications to reference the data source.
#Specify the database or data dictionary path. Type a valid path name to a mapped drive on the server where the Advantage Database Server is installed or the path and file name of your Advantage Data Dictionary. Click Browse to select a database path or check the Data Dictionary check box and then browse to select a data dictionary file. Note Multiple Advantage data sources may need to be defined for your environment. If different settings are needed for ODBC connections in one application, separate data sources may be required.
#Review the options and change them to your desired setup.
#Once the Options are reviewed and/or altered, click OK to exit and save the settings. The new data source is displayed.
#Click Close to exit the ODBC Administrator.

'''ODBC Data Source Entries for Windows''' 
In Microsoft Windows, the entries are registry settings found on HKEY_CURRENT_USER\Software\ODBC\ODBC.INI\ (your unique data source name) or HKEY_LOCAL_MACHINE\Software\ODBC\ODBC.INI (your unique data source name). Unless specified otherwise, all registry entries can be setup by the Advantage ODBC Driver setup utility. See Data Source Setup for Windows and Data Source Setup Screen for more information. ODBC Data Source Keys.

'''ODBC Data Source Keys''' 
The following ODBC registry is '''required''' for the driver to load:
{| class="wikitable"
|-
! '''Registry Entry'''
! '''Comments'''
|-
| DataDirectory=data path
| 'data path' should be a valid path name for files locations (e.g., x:\data). This path is used to automatically select all tables in the specified directory.
|-
| DefaultType=Advantage
| Sets a certain type of database files to use Advantageproprietary ADT/ADI/ADM files.
|-
| ServerTypes=3
| Allows the Driver to use the remote or local server
|}

The following ODBC registry keys are '''optional''':

{| class="wikitable"
|-
! '''Registry Entry'''
! '''Comments'''
|-
| AdvantageLocking=ON \ OFF
| The default is ON to use the Advantage proprietary locking.
|-
| CharSet=OEM \ ANSI
| The default character collation setting is ANSI. If OEM is specified, Language must be indicated as well.
|-
| Language=USA
| Used if CharSet=OEM.
|-
| Description=String
| This is provided for easier administration.
|-
| Locking=RECORD \ FILE
| Indicates whether updates lock the entire file or the individual records that are updated. The default is RECORD.
|-
| MaxTableCloseCache=n
| N is the number of tables to hold in cache when cursors are opened and closed. The default is 25.
|-
| MemoBlockSize=n
| N is the size of the Advantage memo blocks in tables that are created by the ODBC driver. The default value is 8 for Advantage proprietary table (ADT/ADM).
|-
| Rows=TRUE \ FALSE
| Select whether deleted rows are displayed. If True, deleted rows are displayed. The default is False.
|-
| TrimTrailingSpaces=TRUE \ FALSE
| The default is False. If True is specified, trailing spaces in character fields will be removed prior to returning the values to the application.
|}

==Troubleshooting ODBC in 64 Bit Operating Systems==
The Commit ODBC drivers are mainly distributed for 32-bit operating systems; however, the same drivers are supported on the 64-bit operating systems (I.e. Windows 7 x64), and can be used to retrieve data from the CommitCRM database.

 
===Configuring Data Source in 64-Bit Systems===
When installing the ODBC drivers on 64-bit operating systems, the ODBC drivers may not be displayed in the default ODBC manager in windows control panel. In order to view the 32-bit ODBC manager in a 64-bit operating system, you’ll need to browse to '''%windir%\SysWOW64\odbcad32.exe''' and run the 32 bit ODBC Administrator manually. Once the data source has been configured there, you should be able to select the data source in your 3rd party ODBC programs.

 
=Samples=
The Commit API allows you to add/update the following entities:
*Accounts
*Assets
*Tickets
*Charges
*Appointments
*Tasks
*History Notes
*Opportunities
*Documents
*Knowledge Base Articles

Each API method requires a list of parameters which contain the field names and their values. The field names are the Database field names. You can see each field's name within the application (so you can verify which field you are about to update), by right-clicking the field and selecting Field Settings > Advanced Tab > view the Tech. Rec ID field.

You can view the complete list of database fields in the [[Commit_API_Developers_Guide#API_Reference_Manual|API Reference Manual]] above.

Following are samples for using the API by Email and the Programming API. The samples are basic and provide an easy starting point.

See [[API Code Samples]].

=API Reference Manual=

The API allows you to add/update the following entities:
*Accounts
*Assets
*Tickets
*Charges (and Contract-price Charges)
*Appointments
*Tasks
*History Notes
*Opportunities
*Documents
*Knowledge Base Articles

You can find a detailed listing of the database fields in the [[API Reference Manual]].

=See Also=
*[[API Code Samples]]
*[[API Reference Manual]]
*[[Email Connector|Commit Email Connector]]
*[[API by Email and MSP Integration]]
*[[MSP Integration Setup]]
*[http://www.commitcrm.com/sql_database_server.htm Commit SQL Database (CSD)]
*[[Commit SQL Database Installation Guide | Commit SQL Database (CSD) Installation Guide]]

[[Category:User Manuals]]
[[Category:Integration]]

Videos

2010-04-13T21:11:28Z

Reno: /* Additional Tutorials */

For better playback, allow the videos to download before playing.
====Getting Started====
*[http://www.commitcrm.com/videos/commit_crm_getting_started_tutorial_video.htm Getting Started Tutorial] - '''Recommended!''' (15 min.)

====Installation Guides====
*[http://www.commitcrm.com/videos/web_interface_installation_video.htm Web Interface Installation] (6 min.)
*[http://www.commitcrm.com/videos/email_connector_setup_video.htm Email Connector Installation] (12 min.)
*[http://www.commitcrm.com/videos/commit_alert_server_setup_video.htm Alerts Server Installation] (8 min.)
*[http://www.commitcrm.com/videos/commitcrm_upgrades_video.htm Upgrading CommitCRM] (3 min.)

====Contracts & Billing====
*[http://www.commitcrm.com/videos/commit_contracts_introduction_video.htm Contracts Introduction] (4 min.)
*[http://www.commitcrm.com/videos/commit_contracts_global_tutorial_video.htm Global Contracts] (6 min.)
*[http://www.commitcrm.com/videos/commit_contracts_block_of_time_tutorial_video.htm Block Of Time Contracts] (7 min.)
*[http://www.commitcrm.com/videos/commit_contracts_block_of_money_tutorial_video.htm Block Of Money Contracts] (6 min.)
*[http://www.commitcrm.com/videos/commit_contracts_block_of_tickets_tutorial_video.htm Block Of Tickets Contracts] (5 min.)
*[http://www.commitcrm.com/videos/commit_contracts_management_tutorial_video.htm Contract Status and Billing] (7 min.)
*[http://www.commitcrm.com/videos/commit_contracts_contract_price_charges_video.htm Contract-Price Charges] (7 min.)
*[http://www.commitcrm.com/videos/commit_contracts_batch_copy_wizard_video.htm Renewing Recurring Contracts] (4 min.)

====Additional Tutorials====
*[http://www.commitcrm.com/videos/employee_web_interface_tutorial_video.htm Web Interface For Employees] (6 min.)
*[http://www.commitcrm.com/videos/commit_activity_templates_video.htm Managing Activity Templates] (7 min.)
*[http://www.commitcrm.com/videos/commit_report_designer_tutorial_video.htm Report Designer Tutorial] (7 min.)
*[http://commitcrm.com/videos/commitcrm_advanced_filter.html Advanced Filter Tutorial] (5 min.)

 
=====Other Videos=====

'''Manage Accounts:''' Your IT service business Customers, Contacts and Leads
*[http://www.commitcrm.com/videos/new_account.htm See how to add a new Account in Commit™] (33 sec.)

'''Manage IT Service Contracts:''' Block of Time, Block of Money, Block of Tickets, Date Range etc.
*[http://www.commitcrm.com/videos/new_contract.htm See how to create a new Contract for an Account] (1 min, 16 sec.)

'''Manage Tickets''' and increase control over all the open issues, incidents and problems.
*[http://www.commitcrm.com/videos/new_ticket.htm See how to create a new Ticket in Commit™] (45 sec.)
*[http://www.commitcrm.com/videos/charging_ticket.htm See how to add Charges to an open Ticket in Commit™] (42 sec.)

'''Increase Productivity by Dispatching''' the right technician to the right call and by measuring the technician's productivity.

[[Category:Getting Started]]
*[http://www.commitcrm.com/videos/dispatching_ticket.htm See how to dispatch an open service ticket to a technician] (44 sec.)

'''Organize Your Price List''' for products and services.
*[http://www.commitcrm.com/videos/new_labor_item.htm See how to create a new item in Commit™] (41 sec.)

'''Increase Revenues by Easily Entering Charges''' for labor services, expenses, products and parts.
*[http://www.commitcrm.com/videos/new_part_charge.htm See how to create a new Charge in Commit™] (25 sec.)
*[http://www.commitcrm.com/videos/charging_ticket.htm See how to add charges to a service Ticket] (42 sec.)

'''Eliminate paperwork! Easily Manage All Documents''' including MS-Word®, MS-Excel®, presentations, emails, scanned documents etc.
*[http://www.commitcrm.com/videos/importing%20_documents.htm See how to import existing documents folders and link them to your accounts] (45 sec.)

__NOTOC__

[[Category:Setup]]

API Developers Guide

2010-04-07T20:33:15Z

Reno: /* Installing ODBC Driver */

{{usermanuals}}

=Introduction=
CommitCRM provides various tools in order to read/add/update information in the CommitCRM
database. These tools include: Programming API and API by Email for updating the
database, and an ODBC Link for pulling information from the database.
The Commit API provides developers with a set of APIs which allow them to perform
database transactions in order to add and update records in the CommitCRM database. The
API can be used as a Programming API by embedding code which uses the API functions,
or as an API by Email which allows you to send XML formatted emails which will be
processed and executed.

__TOC__

*'''Programming API''' The Commit API provides developers with a set of API functions which can be used in VB, C++, Delphi and any other programming language that lets you use a standard Windows dll file. It provides the ability to create a connection to CommitCRM's database, add new records to the database and update them.

*'''API by Email''' The API by Email allows you to send XML formatted emails which contain database transactions. Commit Email Connector then pulls the incoming XML emails from your POP3 mail server, processes the email and performs the transactions in the XML transaction. XML formatted email gives you an API for the CommitCRM database, which allows you to perform many actions such as linking to external systems, receiving forms submitted from your web site, and more.

*'''ODBC Link''' While the API provides the means for adding and updating information in the database, you should use ODBC Link in order to read information from the database. CommitCRM uses an open database structure and allows other applications to access the database using ODBC (Open Data Base Connectivity) for '''read-only''' purposes. You can use ODBC Link in order to read data from the database and integrate it with an external system (i.e. Crystal reports, or any other application). You may also use the ODBC Link to read Database Record IDs and update existing records. This will be discussed later in this document.

=Glossary=
*'''Commit API (Application Programming Interface)''' - CommitCRM provides an API which allows you to add and update records in the CommitCRM database. The API includes a list of possible actions and parameters.

*'''ODBC Link (Open Data Base Connectivity)''' - ODBC is a function library which provides a common API for ODBC compliant databases. CommitCRM provides an open database and allows other applications to access the database using ODBC for '''read-only''' purposes.

*'''Record''' - Each entity in the CommitCRM database (such as Ticket, Account, Asset, Item, Appointment, Task, etc.) is considered a "record".

*'''Database fields''' - Each record contains a list of fields, each of which holds the record's data.

*'''Transaction''' – All additions or updates to record in the database are done by using a transaction. Each transaction includes the operation you wish to perform, the data type you wish to add/update and the additional parameters (database fields and their values).

*'''Transaction Parameters''' - Each transaction contains the parameters for performing the transaction: record type, list of database fields and a list of the values to be updated in these fields.

*'''External Application''' - This refers to the external program which integrates with CommitCRM in order to update the database. This name should be passed when performing updates to the database, and it will be saved in the CommitCRM record to indicate who performed the changes.

*'''Record ID (REC ID)''' - Each record in CommitCRM has a '''unique Record ID''' which is created when adding the record to the database. Every ID is 20 characters and should be transferred with the API transaction when you need to update an existing record.

=Using Commit API=
Commit API allows you to add and update records in the CommitCRM database, such as
Accounts, Tickets, Assets, Items, Appointments, Tasks and more.

The updates are performed using transactions, where each transaction includes the
operation you wish to perform, the data type you wish to add/update, and any additional
parameters (i.e. record type, database fields and their values).

Every record added to the system is assigned a unique Record ID (REC ID) which is the
database identifier for this record.

The Commit API allows you to perform the following operations.

*'''Add new records''' - if no Record ID is passed in the transaction, the API assumes that this is a new record, adds it to the system and creates a new Record ID for it.

*'''Update existing records''' - if the record ID is passed in the transaction, and the record exists, the system will update the record with the information in the transaction.

In both cases, the system will try to set default values for fields which do not exist in the
incoming transaction. If it fails, the action will fail with an error.

Note that in order to '''read data''' from the CommitCRM database, you should use the ODBC
Link, which provides a read-only link for the CommitCRM database. See more details in
[[#Retrieving data using ODBC|Retrieving data using ODBC]].

==Workflow==
Following is a sample work-flow, which demonstrates the process of adding a new Account, and then adding a new Ticket to this Account, using the Commit API.

Note that the API can return two parameters to the External Application:
#The Commit REC ID - when adding new records to the database, this will contains the new record ID.
#The ExternalTransactionID (relevant for XML transaction only) - In case the external application passes a parameter to be returned with the response, the ExternalTransactionID will be returned as-is to in the response.

The External Application should keep the REC ID which is returned from the API response. This allows you to later update the existing records with new data or add records related to it (such as opening a Ticket under the Account).

[[File:flow.gif|center]]

==Updating existing records==
In order to update an already existing record in the database (e.g. add a Ticket to an
Account, update an Account's phone number, add a new Charge to an existing Ticket,
etc.), you should pass the record's unique identifier to the API so it will update the
existing record rather than create a new Account. The record's unique identifier is
referred to as the Record ID (REC ID).

The Record ID can be obtained in the following ways:
#'''API Response''' (as in the flow above) - You can extract the newly created Record ID from the Email Response when adding new records with the API. This requires the developer to process the API responses, and extract the returning REC ID for each newly added record.
#'''ODBC Link''' - Use the ODBC Link to find relevant records (Accounts, Tickets, etc.), and read all information from the database, including the unique Record ID.
#'''Manually''' - from the Account's Notes tab, at the bottom, right-click the REC ID field and copy it.

Once you have obtained the Record ID you can pass the Record ID as a parameter for the
API and update this record.

=Programming API=
The Programming API allows you access the CommitCRM database and perform transactions
from within a program (using various programming language). This means you can embed
code which accesses the CommitCRM database from within your own application, and add
your own functionality which updates the database.

The programming API executes database transactions. Each transaction uses API methods
provides by the API dll file which is located in the CommitCRM installation. Both the
Programming API and the API by Email use the same dll for performing the transactions.

Note that the API provides the tools needed for adding/updating information in the
database. In order to retrieve data, you should use the ODBC link which allows you to
connect to the database and retrieve data directly from the tables. You can read more
about it in the [[Commit_API_Developers_Guide#ODBC_Data_Retrieval|ODBC Data Retrieval]] section.

You can find more information and samples in the [[API Code Samples]] section.

=API by Email (XML transaction)=
The API by Email operates under the Commit Email Connector module, which
automatically processes incoming emails arriving at a defined public email address. The
Email may contain XML formatted messages which contain API transactions, and provides
a full API to CommitCRM.

The Email Connector pulls incoming emails from your POP3 mail server, and processes the
email. When an email containing XML formatted message is detected, the system analyzes
the XML content of the email and performs the transactions written in the XML. You may
set the Email Connector to send automatic replies in response to XML formatted email.

The API by Email executes database transactions. Each transaction uses API methods
provided by the API dll file which is located in the CommitCRM installation. Both the
Programming API and the API by Email use the same dll for performing the transactions.

Note that the API provides the tools for adding/updating information in the database. In
order to retrieve data, you should use the ODBC link which allows you to connect to the
database and retrieve data directly from the tables. You can read more about it in the
[[Commit_API_Developers_Guide#ODBC_Data_Retrieval|ODBC Data Retrieval]] section.

You can find more information and samples in [[API Code Samples#XML samples|XML samples]].

=ODBC Data Retrieval=
CommitCRM uses an open database and allows other applications to access it using ODBC
(Open Data Base Connectivity) for '''read-only''' purposes. While the API provides the means
for adding and updating information in the database, it is preferred to use ODBC to read
information from the database.

You can use ODBC Link to read data from the database and integrate it with an external
system (i.e. Crystal reports, or any other application). You may also use the ODBC Link in
order to read the Database Record ID and update existing records (see [[Commit_API_Developers_Guide#Updating_existing_records|Updating existing records]]).

'''Activation Notes:'''

*The ODBC drivers are well tested and work well, however, please note that the Commit Support team doesn't provide "pure ODBC" support.

*NEVER use ODBC to modify or delete data; use it for READ purposes only. Modifying data should be done using the Commit API.

*The ODBC Link can be used with your installed version of CommitCRM, and only requires installing an external driver. Before working with the API we recommend that you '''backup the database'''.

Below are the database table names and their meaning:
{| class="wikitable"
|-
! '''CommitCRM Record'''
! '''Database Table Name'''
|-
| Accounts
| Cards
|-
| Tickets
| Tickets
|-
| Charges
| Slips
|-
| Assets
| Assets
|-
| Appointments
| Events
|-
| Tasks
| Events
|-
| History Notes
| NoteBook
|-
| Opportunities
| Opps
|-
| Documents
| Docs
|-
| Knowledge Base
| KBArticles
|}

For the database fields list, please refer to [[Commit_API_Developers_Guide#API_Reference_Manual|API Reference Manual]] section.
You can find detailed instructions for using the ODBC Link in the [[Commit_API_Developers_Guide#Installing_ODBC_Driver|Installing ODBC Driver]] section.

==Installing ODBC Driver==
'''Product Overview''' 
The Advantage ODBC Driver is an ODBC version 3 driver based on the Advantage Client Engine that provides SQL access to the Advantage Database Server. The driver provides
full support for the "Minimum" ODBC SQL grammar specification, as well as many functions
included in the "Core" and "Extended" grammar specifications. When used with the
Advantage Database Server, ODBC users can have the
application stability, performance and reduced network traffic benefits of client/server
architecture.

'''Installation on Windows''' 
Like other ODBC drivers, the Advantage ODBC Driver is installed and managed using the
ODBC Administrator Utility. This utility works with the ODBC Driver Manager to configure
ODBC data sources. At runtime, the ODBC Driver Manager works with available drivers and
their configured data sources. If you have previously installed ODBC drivers, the ODBC Administrator may already be installed on your workstation. The icon for the Administrator is usually found in the Control Panel.

To install the Advantage ODBC Driver:
#Download the ODBC driver version that corresponds with your Advantage SQL Database Server version from the following links: (The Advantage Version number can be found in the [[Media:ADS_Version.jpg|Advantage Configuration Utility]] located on the CommitCRM Server) '''[http://www.commitcrm.com/downloads/commit-odbc-9-0-0-7.exe ODBC Driver Version 9.0] [http://www.commitcrm.com/downloads/commit-odbc-8-1-0-26.exe ODBC Driver Version 8.1] '''
#Run the Setup program.
#Proceed through the setup windows to complete installation.

'''Data Source Setup for Windows''' 
Once the Advantage ODBC Driver is installed, a data source needs to be configured to use
the Advantage ODBC Driver. The data source is an entry in the Windows Registry. When a
data source is defined for the Advantage Driver, all information specific to the Advantage
Driver and database files is stored under the Data Source entry in the Windows 95/98/ME/
NT/2000/2003/XP Registry. 
The database files and indexes must be stored on your file server, and the Advantage
Database Server must be loaded in order to access the files.

The Data Source settings may be modified at any time. Using the ODBC Administrator, you
may modify the Data Source and Option settings.
For specific information about the screen fields see the Data Source Setup Screen.

'''To Setup the Data Source:'''
#From the ODBC Administrator, click Add.
#Highlight the Advantage SQL ODBC line, and click OK.
#Type a unique data source name. For example, type AdvData. This name is used by applications to reference the data source.
#Specify the database or data dictionary path. Type a valid path name to a mapped drive on the server where the Advantage Database Server is installed or the path and file name of your Advantage Data Dictionary. Click Browse to select a database path or check the Data Dictionary check box and then browse to select a data dictionary file. Note Multiple Advantage data sources may need to be defined for your environment. If different settings are needed for ODBC connections in one application, separate data sources may be required.
#Review the options and change them to your desired setup.
#Once the Options are reviewed and/or altered, click OK to exit and save the settings. The new data source is displayed.
#Click Close to exit the ODBC Administrator.

'''ODBC Data Source Entries for Windows''' 
In Microsoft Windows, the entries are registry settings found on HKEY_CURRENT_USER\Software\ODBC\ODBC.INI\ (your unique data source name) or HKEY_LOCAL_MACHINE\Software\ODBC\ODBC.INI (your unique data source name). Unless specified otherwise, all registry entries can be setup by the Advantage ODBC Driver setup utility. See Data Source Setup for Windows and Data Source Setup Screen for more information. ODBC Data Source Keys.

'''ODBC Data Source Keys''' 
The following ODBC registry is '''required''' for the driver to load:
{| class="wikitable"
|-
! '''Registry Entry'''
! '''Comments'''
|-
| DataDirectory=data path
| 'data path' should be a valid path name for files locations (e.g., x:\data). This path is used to automatically select all tables in the specified directory.
|-
| DefaultType=Advantage
| Sets a certain type of database files to use Advantageproprietary ADT/ADI/ADM files.
|-
| ServerTypes=3
| Allows the Driver to use the remote or local server
|}

The following ODBC registry keys are '''optional''':

{| class="wikitable"
|-
! '''Registry Entry'''
! '''Comments'''
|-
| AdvantageLocking=ON \ OFF
| The default is ON to use the Advantage proprietary locking.
|-
| CharSet=OEM \ ANSI
| The default character collation setting is ANSI. If OEM is specified, Language must be indicated as well.
|-
| Language=USA
| Used if CharSet=OEM.
|-
| Description=String
| This is provided for easier administration.
|-
| Locking=RECORD \ FILE
| Indicates whether updates lock the entire file or the individual records that are updated. The default is RECORD.
|-
| MaxTableCloseCache=n
| N is the number of tables to hold in cache when cursors are opened and closed. The default is 25.
|-
| MemoBlockSize=n
| N is the size of the Advantage memo blocks in tables that are created by the ODBC driver. The default value is 8 for Advantage proprietary table (ADT/ADM).
|-
| Rows=TRUE \ FALSE
| Select whether deleted rows are displayed. If True, deleted rows are displayed. The default is False.
|-
| TrimTrailingSpaces=TRUE \ FALSE
| The default is False. If True is specified, trailing spaces in character fields will be removed prior to returning the values to the application.
|}

==Troubleshooting ODBC in 64 Bit Operating Systems==
The Commit ODBC drivers are mainly distributed for 32-bit operating systems; however, the same drivers are supported on the 64-bit operating systems (I.e. Windows 7 x64), and can be used to retrieve data from the CommitCRM database.

 
===Configuring Data Source in 64-Bit Systems===
When installing the ODBC drivers on 64-bit operating systems, the ODBC drivers may not be displayed in the default ODBC manager in windows control panel. In order to view the 32-bit ODBC manager in a 64-bit operating system, you’ll need to browse to '''%windir%\SysWOW64\odbcad32.exe''' and run the 32 bit ODBC Administrator manually. Once the data source has been configured there, you should be able to select the data source in your 3rd party ODBC programs.

 
=Samples=
The Commit API allows you to add/update the following entities:
*Accounts
*Assets
*Tickets
*Charges
*Appointments
*Tasks
*History Notes
*Opportunities
*Documents
*Knowledge Base Articles

Each API method requires a list of parameters which contain the field names and their values. The field names are the Database field names. You can see each field's name within the application (so you can verify which field you are about to update), by right-clicking the field and selecting Field Settings > Advanced Tab > view the Tech. Rec ID field.

You can view the complete list of database fields in the [[Commit_API_Developers_Guide#API_Reference_Manual|API Reference Manual]] above.

Following are samples for using the API by Email and the Programming API. The samples are basic and provide an easy starting point.

See [[API Code Samples]].

=API Reference Manual=

The API allows you to add/update the following entities:
*Accounts
*Assets
*Tickets
*Charges (and Contract-price Charges)
*Appointments
*Tasks
*History Notes
*Opportunities
*Documents
*Knowledge Base Articles

You can find a detailed listing of the database fields in the [[API Reference Manual]].

=See Also=
*[[API Code Samples]]
*[[API Reference Manual]]
*[[Email Connector|Commit Email Connector]]
*[[API by Email and MSP Integration]]
*[[MSP Integration Setup]]
*[http://www.commitcrm.com/sql_database_server.htm Commit SQL Database (CSD)]
*[[Commit SQL Database Installation Guide | Commit SQL Database (CSD) Installation Guide]]

[[Category:User Manuals]]
[[Category:Integration]]

API Developers Guide

2010-04-07T20:26:43Z

Reno: /* Installing ODBC Driver */

{{usermanuals}}

=Introduction=
CommitCRM provides various tools in order to read/add/update information in the CommitCRM
database. These tools include: Programming API and API by Email for updating the
database, and an ODBC Link for pulling information from the database.
The Commit API provides developers with a set of APIs which allow them to perform
database transactions in order to add and update records in the CommitCRM database. The
API can be used as a Programming API by embedding code which uses the API functions,
or as an API by Email which allows you to send XML formatted emails which will be
processed and executed.

__TOC__

*'''Programming API''' The Commit API provides developers with a set of API functions which can be used in VB, C++, Delphi and any other programming language that lets you use a standard Windows dll file. It provides the ability to create a connection to CommitCRM's database, add new records to the database and update them.

*'''API by Email''' The API by Email allows you to send XML formatted emails which contain database transactions. Commit Email Connector then pulls the incoming XML emails from your POP3 mail server, processes the email and performs the transactions in the XML transaction. XML formatted email gives you an API for the CommitCRM database, which allows you to perform many actions such as linking to external systems, receiving forms submitted from your web site, and more.

*'''ODBC Link''' While the API provides the means for adding and updating information in the database, you should use ODBC Link in order to read information from the database. CommitCRM uses an open database structure and allows other applications to access the database using ODBC (Open Data Base Connectivity) for '''read-only''' purposes. You can use ODBC Link in order to read data from the database and integrate it with an external system (i.e. Crystal reports, or any other application). You may also use the ODBC Link to read Database Record IDs and update existing records. This will be discussed later in this document.

=Glossary=
*'''Commit API (Application Programming Interface)''' - CommitCRM provides an API which allows you to add and update records in the CommitCRM database. The API includes a list of possible actions and parameters.

*'''ODBC Link (Open Data Base Connectivity)''' - ODBC is a function library which provides a common API for ODBC compliant databases. CommitCRM provides an open database and allows other applications to access the database using ODBC for '''read-only''' purposes.

*'''Record''' - Each entity in the CommitCRM database (such as Ticket, Account, Asset, Item, Appointment, Task, etc.) is considered a "record".

*'''Database fields''' - Each record contains a list of fields, each of which holds the record's data.

*'''Transaction''' – All additions or updates to record in the database are done by using a transaction. Each transaction includes the operation you wish to perform, the data type you wish to add/update and the additional parameters (database fields and their values).

*'''Transaction Parameters''' - Each transaction contains the parameters for performing the transaction: record type, list of database fields and a list of the values to be updated in these fields.

*'''External Application''' - This refers to the external program which integrates with CommitCRM in order to update the database. This name should be passed when performing updates to the database, and it will be saved in the CommitCRM record to indicate who performed the changes.

*'''Record ID (REC ID)''' - Each record in CommitCRM has a '''unique Record ID''' which is created when adding the record to the database. Every ID is 20 characters and should be transferred with the API transaction when you need to update an existing record.

=Using Commit API=
Commit API allows you to add and update records in the CommitCRM database, such as
Accounts, Tickets, Assets, Items, Appointments, Tasks and more.

The updates are performed using transactions, where each transaction includes the
operation you wish to perform, the data type you wish to add/update, and any additional
parameters (i.e. record type, database fields and their values).

Every record added to the system is assigned a unique Record ID (REC ID) which is the
database identifier for this record.

The Commit API allows you to perform the following operations.

*'''Add new records''' - if no Record ID is passed in the transaction, the API assumes that this is a new record, adds it to the system and creates a new Record ID for it.

*'''Update existing records''' - if the record ID is passed in the transaction, and the record exists, the system will update the record with the information in the transaction.

In both cases, the system will try to set default values for fields which do not exist in the
incoming transaction. If it fails, the action will fail with an error.

Note that in order to '''read data''' from the CommitCRM database, you should use the ODBC
Link, which provides a read-only link for the CommitCRM database. See more details in
[[#Retrieving data using ODBC|Retrieving data using ODBC]].

==Workflow==
Following is a sample work-flow, which demonstrates the process of adding a new Account, and then adding a new Ticket to this Account, using the Commit API.

Note that the API can return two parameters to the External Application:
#The Commit REC ID - when adding new records to the database, this will contains the new record ID.
#The ExternalTransactionID (relevant for XML transaction only) - In case the external application passes a parameter to be returned with the response, the ExternalTransactionID will be returned as-is to in the response.

The External Application should keep the REC ID which is returned from the API response. This allows you to later update the existing records with new data or add records related to it (such as opening a Ticket under the Account).

[[File:flow.gif|center]]

==Updating existing records==
In order to update an already existing record in the database (e.g. add a Ticket to an
Account, update an Account's phone number, add a new Charge to an existing Ticket,
etc.), you should pass the record's unique identifier to the API so it will update the
existing record rather than create a new Account. The record's unique identifier is
referred to as the Record ID (REC ID).

The Record ID can be obtained in the following ways:
#'''API Response''' (as in the flow above) - You can extract the newly created Record ID from the Email Response when adding new records with the API. This requires the developer to process the API responses, and extract the returning REC ID for each newly added record.
#'''ODBC Link''' - Use the ODBC Link to find relevant records (Accounts, Tickets, etc.), and read all information from the database, including the unique Record ID.
#'''Manually''' - from the Account's Notes tab, at the bottom, right-click the REC ID field and copy it.

Once you have obtained the Record ID you can pass the Record ID as a parameter for the
API and update this record.

=Programming API=
The Programming API allows you access the CommitCRM database and perform transactions
from within a program (using various programming language). This means you can embed
code which accesses the CommitCRM database from within your own application, and add
your own functionality which updates the database.

The programming API executes database transactions. Each transaction uses API methods
provides by the API dll file which is located in the CommitCRM installation. Both the
Programming API and the API by Email use the same dll for performing the transactions.

Note that the API provides the tools needed for adding/updating information in the
database. In order to retrieve data, you should use the ODBC link which allows you to
connect to the database and retrieve data directly from the tables. You can read more
about it in the [[Commit_API_Developers_Guide#ODBC_Data_Retrieval|ODBC Data Retrieval]] section.

You can find more information and samples in the [[API Code Samples]] section.

=API by Email (XML transaction)=
The API by Email operates under the Commit Email Connector module, which
automatically processes incoming emails arriving at a defined public email address. The
Email may contain XML formatted messages which contain API transactions, and provides
a full API to CommitCRM.

The Email Connector pulls incoming emails from your POP3 mail server, and processes the
email. When an email containing XML formatted message is detected, the system analyzes
the XML content of the email and performs the transactions written in the XML. You may
set the Email Connector to send automatic replies in response to XML formatted email.

The API by Email executes database transactions. Each transaction uses API methods
provided by the API dll file which is located in the CommitCRM installation. Both the
Programming API and the API by Email use the same dll for performing the transactions.

Note that the API provides the tools for adding/updating information in the database. In
order to retrieve data, you should use the ODBC link which allows you to connect to the
database and retrieve data directly from the tables. You can read more about it in the
[[Commit_API_Developers_Guide#ODBC_Data_Retrieval|ODBC Data Retrieval]] section.

You can find more information and samples in [[API Code Samples#XML samples|XML samples]].

=ODBC Data Retrieval=
CommitCRM uses an open database and allows other applications to access it using ODBC
(Open Data Base Connectivity) for '''read-only''' purposes. While the API provides the means
for adding and updating information in the database, it is preferred to use ODBC to read
information from the database.

You can use ODBC Link to read data from the database and integrate it with an external
system (i.e. Crystal reports, or any other application). You may also use the ODBC Link in
order to read the Database Record ID and update existing records (see [[Commit_API_Developers_Guide#Updating_existing_records|Updating existing records]]).

'''Activation Notes:'''

*The ODBC drivers are well tested and work well, however, please note that the Commit Support team doesn't provide "pure ODBC" support.

*NEVER use ODBC to modify or delete data; use it for READ purposes only. Modifying data should be done using the Commit API.

*The ODBC Link can be used with your installed version of CommitCRM, and only requires installing an external driver. Before working with the API we recommend that you '''backup the database'''.

Below are the database table names and their meaning:
{| class="wikitable"
|-
! '''CommitCRM Record'''
! '''Database Table Name'''
|-
| Accounts
| Cards
|-
| Tickets
| Tickets
|-
| Charges
| Slips
|-
| Assets
| Assets
|-
| Appointments
| Events
|-
| Tasks
| Events
|-
| History Notes
| NoteBook
|-
| Opportunities
| Opps
|-
| Documents
| Docs
|-
| Knowledge Base
| KBArticles
|}

For the database fields list, please refer to [[Commit_API_Developers_Guide#API_Reference_Manual|API Reference Manual]] section.
You can find detailed instructions for using the ODBC Link in the [[Commit_API_Developers_Guide#Installing_ODBC_Driver|Installing ODBC Driver]] section.

==Installing ODBC Driver==
'''Product Overview''' 
The Advantage ODBC Driver is an ODBC version 3 driver based on the Advantage Client Engine that provides SQL access to the Advantage Database Server. The driver provides
full support for the "Minimum" ODBC SQL grammar specification, as well as many functions
included in the "Core" and "Extended" grammar specifications. When used with the
Advantage Database Server, ODBC users can have the
application stability, performance and reduced network traffic benefits of client/server
architecture.

'''Installation on Windows''' 
Like other ODBC drivers, the Advantage ODBC Driver is installed and managed using the
ODBC Administrator Utility. This utility works with the ODBC Driver Manager to configure
ODBC data sources. At runtime, the ODBC Driver Manager works with available drivers and
their configured data sources. If you have previously installed ODBC drivers, the ODBC Administrator may already be installed on your workstation. The icon for the Administrator is usually found in the Control Panel.

To install the Advantage ODBC Driver:
#Download the ODBC driver version that corresponds with your Advantage SQL Database Server version from the following links: (The Advantage Version number can be found in the [[Media:ADS_Version.jpg|Advantage Configuration Utility]]) '''[http://www.commitcrm.com/downloads/commit-odbc-9-0-0-7.exe ODBC Driver Version 9.0] [http://www.commitcrm.com/downloads/commit-odbc-8-1-0-26.exe ODBC Driver Version 8.1] '''
#Run the Setup program.
#Proceed through the setup windows to complete installation.

'''Data Source Setup for Windows''' 
Once the Advantage ODBC Driver is installed, a data source needs to be configured to use
the Advantage ODBC Driver. The data source is an entry in the Windows Registry. When a
data source is defined for the Advantage Driver, all information specific to the Advantage
Driver and database files is stored under the Data Source entry in the Windows 95/98/ME/
NT/2000/2003/XP Registry. 
The database files and indexes must be stored on your file server, and the Advantage
Database Server must be loaded in order to access the files.

The Data Source settings may be modified at any time. Using the ODBC Administrator, you
may modify the Data Source and Option settings.
For specific information about the screen fields see the Data Source Setup Screen.

'''To Setup the Data Source:'''
#From the ODBC Administrator, click Add.
#Highlight the Advantage SQL ODBC line, and click OK.
#Type a unique data source name. For example, type AdvData. This name is used by applications to reference the data source.
#Specify the database or data dictionary path. Type a valid path name to a mapped drive on the server where the Advantage Database Server is installed or the path and file name of your Advantage Data Dictionary. Click Browse to select a database path or check the Data Dictionary check box and then browse to select a data dictionary file. Note Multiple Advantage data sources may need to be defined for your environment. If different settings are needed for ODBC connections in one application, separate data sources may be required.
#Review the options and change them to your desired setup.
#Once the Options are reviewed and/or altered, click OK to exit and save the settings. The new data source is displayed.
#Click Close to exit the ODBC Administrator.

'''ODBC Data Source Entries for Windows''' 
In Microsoft Windows, the entries are registry settings found on HKEY_CURRENT_USER\Software\ODBC\ODBC.INI\ (your unique data source name) or HKEY_LOCAL_MACHINE\Software\ODBC\ODBC.INI (your unique data source name). Unless specified otherwise, all registry entries can be setup by the Advantage ODBC Driver setup utility. See Data Source Setup for Windows and Data Source Setup Screen for more information. ODBC Data Source Keys.

'''ODBC Data Source Keys''' 
The following ODBC registry is '''required''' for the driver to load:
{| class="wikitable"
|-
! '''Registry Entry'''
! '''Comments'''
|-
| DataDirectory=data path
| 'data path' should be a valid path name for files locations (e.g., x:\data). This path is used to automatically select all tables in the specified directory.
|-
| DefaultType=Advantage
| Sets a certain type of database files to use Advantageproprietary ADT/ADI/ADM files.
|-
| ServerTypes=3
| Allows the Driver to use the remote or local server
|}

The following ODBC registry keys are '''optional''':

{| class="wikitable"
|-
! '''Registry Entry'''
! '''Comments'''
|-
| AdvantageLocking=ON \ OFF
| The default is ON to use the Advantage proprietary locking.
|-
| CharSet=OEM \ ANSI
| The default character collation setting is ANSI. If OEM is specified, Language must be indicated as well.
|-
| Language=USA
| Used if CharSet=OEM.
|-
| Description=String
| This is provided for easier administration.
|-
| Locking=RECORD \ FILE
| Indicates whether updates lock the entire file or the individual records that are updated. The default is RECORD.
|-
| MaxTableCloseCache=n
| N is the number of tables to hold in cache when cursors are opened and closed. The default is 25.
|-
| MemoBlockSize=n
| N is the size of the Advantage memo blocks in tables that are created by the ODBC driver. The default value is 8 for Advantage proprietary table (ADT/ADM).
|-
| Rows=TRUE \ FALSE
| Select whether deleted rows are displayed. If True, deleted rows are displayed. The default is False.
|-
| TrimTrailingSpaces=TRUE \ FALSE
| The default is False. If True is specified, trailing spaces in character fields will be removed prior to returning the values to the application.
|}

==Troubleshooting ODBC in 64 Bit Operating Systems==
The Commit ODBC drivers are mainly distributed for 32-bit operating systems; however, the same drivers are supported on the 64-bit operating systems (I.e. Windows 7 x64), and can be used to retrieve data from the CommitCRM database.

 
===Configuring Data Source in 64-Bit Systems===
When installing the ODBC drivers on 64-bit operating systems, the ODBC drivers may not be displayed in the default ODBC manager in windows control panel. In order to view the 32-bit ODBC manager in a 64-bit operating system, you’ll need to browse to '''%windir%\SysWOW64\odbcad32.exe''' and run the 32 bit ODBC Administrator manually. Once the data source has been configured there, you should be able to select the data source in your 3rd party ODBC programs.

 
=Samples=
The Commit API allows you to add/update the following entities:
*Accounts
*Assets
*Tickets
*Charges
*Appointments
*Tasks
*History Notes
*Opportunities
*Documents
*Knowledge Base Articles

Each API method requires a list of parameters which contain the field names and their values. The field names are the Database field names. You can see each field's name within the application (so you can verify which field you are about to update), by right-clicking the field and selecting Field Settings > Advanced Tab > view the Tech. Rec ID field.

You can view the complete list of database fields in the [[Commit_API_Developers_Guide#API_Reference_Manual|API Reference Manual]] above.

Following are samples for using the API by Email and the Programming API. The samples are basic and provide an easy starting point.

See [[API Code Samples]].

=API Reference Manual=

The API allows you to add/update the following entities:
*Accounts
*Assets
*Tickets
*Charges (and Contract-price Charges)
*Appointments
*Tasks
*History Notes
*Opportunities
*Documents
*Knowledge Base Articles

You can find a detailed listing of the database fields in the [[API Reference Manual]].

=See Also=
*[[API Code Samples]]
*[[API Reference Manual]]
*[[Email Connector|Commit Email Connector]]
*[[API by Email and MSP Integration]]
*[[MSP Integration Setup]]
*[http://www.commitcrm.com/sql_database_server.htm Commit SQL Database (CSD)]
*[[Commit SQL Database Installation Guide | Commit SQL Database (CSD) Installation Guide]]

[[Category:User Manuals]]
[[Category:Integration]]

File:ADS Version.jpg

2010-04-07T20:25:06Z

Reno:

API Developers Guide

2010-04-07T19:55:35Z

Reno: /* Installing ODBC Driver */

{{usermanuals}}

=Introduction=
CommitCRM provides various tools in order to read/add/update information in the CommitCRM
database. These tools include: Programming API and API by Email for updating the
database, and an ODBC Link for pulling information from the database.
The Commit API provides developers with a set of APIs which allow them to perform
database transactions in order to add and update records in the CommitCRM database. The
API can be used as a Programming API by embedding code which uses the API functions,
or as an API by Email which allows you to send XML formatted emails which will be
processed and executed.

__TOC__

*'''Programming API''' The Commit API provides developers with a set of API functions which can be used in VB, C++, Delphi and any other programming language that lets you use a standard Windows dll file. It provides the ability to create a connection to CommitCRM's database, add new records to the database and update them.

*'''API by Email''' The API by Email allows you to send XML formatted emails which contain database transactions. Commit Email Connector then pulls the incoming XML emails from your POP3 mail server, processes the email and performs the transactions in the XML transaction. XML formatted email gives you an API for the CommitCRM database, which allows you to perform many actions such as linking to external systems, receiving forms submitted from your web site, and more.

*'''ODBC Link''' While the API provides the means for adding and updating information in the database, you should use ODBC Link in order to read information from the database. CommitCRM uses an open database structure and allows other applications to access the database using ODBC (Open Data Base Connectivity) for '''read-only''' purposes. You can use ODBC Link in order to read data from the database and integrate it with an external system (i.e. Crystal reports, or any other application). You may also use the ODBC Link to read Database Record IDs and update existing records. This will be discussed later in this document.

=Glossary=
*'''Commit API (Application Programming Interface)''' - CommitCRM provides an API which allows you to add and update records in the CommitCRM database. The API includes a list of possible actions and parameters.

*'''ODBC Link (Open Data Base Connectivity)''' - ODBC is a function library which provides a common API for ODBC compliant databases. CommitCRM provides an open database and allows other applications to access the database using ODBC for '''read-only''' purposes.

*'''Record''' - Each entity in the CommitCRM database (such as Ticket, Account, Asset, Item, Appointment, Task, etc.) is considered a "record".

*'''Database fields''' - Each record contains a list of fields, each of which holds the record's data.

*'''Transaction''' – All additions or updates to record in the database are done by using a transaction. Each transaction includes the operation you wish to perform, the data type you wish to add/update and the additional parameters (database fields and their values).

*'''Transaction Parameters''' - Each transaction contains the parameters for performing the transaction: record type, list of database fields and a list of the values to be updated in these fields.

*'''External Application''' - This refers to the external program which integrates with CommitCRM in order to update the database. This name should be passed when performing updates to the database, and it will be saved in the CommitCRM record to indicate who performed the changes.

*'''Record ID (REC ID)''' - Each record in CommitCRM has a '''unique Record ID''' which is created when adding the record to the database. Every ID is 20 characters and should be transferred with the API transaction when you need to update an existing record.

=Using Commit API=
Commit API allows you to add and update records in the CommitCRM database, such as
Accounts, Tickets, Assets, Items, Appointments, Tasks and more.

The updates are performed using transactions, where each transaction includes the
operation you wish to perform, the data type you wish to add/update, and any additional
parameters (i.e. record type, database fields and their values).

Every record added to the system is assigned a unique Record ID (REC ID) which is the
database identifier for this record.

The Commit API allows you to perform the following operations.

*'''Add new records''' - if no Record ID is passed in the transaction, the API assumes that this is a new record, adds it to the system and creates a new Record ID for it.

*'''Update existing records''' - if the record ID is passed in the transaction, and the record exists, the system will update the record with the information in the transaction.

In both cases, the system will try to set default values for fields which do not exist in the
incoming transaction. If it fails, the action will fail with an error.

Note that in order to '''read data''' from the CommitCRM database, you should use the ODBC
Link, which provides a read-only link for the CommitCRM database. See more details in
[[#Retrieving data using ODBC|Retrieving data using ODBC]].

==Workflow==
Following is a sample work-flow, which demonstrates the process of adding a new Account, and then adding a new Ticket to this Account, using the Commit API.

Note that the API can return two parameters to the External Application:
#The Commit REC ID - when adding new records to the database, this will contains the new record ID.
#The ExternalTransactionID (relevant for XML transaction only) - In case the external application passes a parameter to be returned with the response, the ExternalTransactionID will be returned as-is to in the response.

The External Application should keep the REC ID which is returned from the API response. This allows you to later update the existing records with new data or add records related to it (such as opening a Ticket under the Account).

[[File:flow.gif|center]]

==Updating existing records==
In order to update an already existing record in the database (e.g. add a Ticket to an
Account, update an Account's phone number, add a new Charge to an existing Ticket,
etc.), you should pass the record's unique identifier to the API so it will update the
existing record rather than create a new Account. The record's unique identifier is
referred to as the Record ID (REC ID).

The Record ID can be obtained in the following ways:
#'''API Response''' (as in the flow above) - You can extract the newly created Record ID from the Email Response when adding new records with the API. This requires the developer to process the API responses, and extract the returning REC ID for each newly added record.
#'''ODBC Link''' - Use the ODBC Link to find relevant records (Accounts, Tickets, etc.), and read all information from the database, including the unique Record ID.
#'''Manually''' - from the Account's Notes tab, at the bottom, right-click the REC ID field and copy it.

Once you have obtained the Record ID you can pass the Record ID as a parameter for the
API and update this record.

=Programming API=
The Programming API allows you access the CommitCRM database and perform transactions
from within a program (using various programming language). This means you can embed
code which accesses the CommitCRM database from within your own application, and add
your own functionality which updates the database.

The programming API executes database transactions. Each transaction uses API methods
provides by the API dll file which is located in the CommitCRM installation. Both the
Programming API and the API by Email use the same dll for performing the transactions.

Note that the API provides the tools needed for adding/updating information in the
database. In order to retrieve data, you should use the ODBC link which allows you to
connect to the database and retrieve data directly from the tables. You can read more
about it in the [[Commit_API_Developers_Guide#ODBC_Data_Retrieval|ODBC Data Retrieval]] section.

You can find more information and samples in the [[API Code Samples]] section.

=API by Email (XML transaction)=
The API by Email operates under the Commit Email Connector module, which
automatically processes incoming emails arriving at a defined public email address. The
Email may contain XML formatted messages which contain API transactions, and provides
a full API to CommitCRM.

The Email Connector pulls incoming emails from your POP3 mail server, and processes the
email. When an email containing XML formatted message is detected, the system analyzes
the XML content of the email and performs the transactions written in the XML. You may
set the Email Connector to send automatic replies in response to XML formatted email.

The API by Email executes database transactions. Each transaction uses API methods
provided by the API dll file which is located in the CommitCRM installation. Both the
Programming API and the API by Email use the same dll for performing the transactions.

Note that the API provides the tools for adding/updating information in the database. In
order to retrieve data, you should use the ODBC link which allows you to connect to the
database and retrieve data directly from the tables. You can read more about it in the
[[Commit_API_Developers_Guide#ODBC_Data_Retrieval|ODBC Data Retrieval]] section.

You can find more information and samples in [[API Code Samples#XML samples|XML samples]].

=ODBC Data Retrieval=
CommitCRM uses an open database and allows other applications to access it using ODBC
(Open Data Base Connectivity) for '''read-only''' purposes. While the API provides the means
for adding and updating information in the database, it is preferred to use ODBC to read
information from the database.

You can use ODBC Link to read data from the database and integrate it with an external
system (i.e. Crystal reports, or any other application). You may also use the ODBC Link in
order to read the Database Record ID and update existing records (see [[Commit_API_Developers_Guide#Updating_existing_records|Updating existing records]]).

'''Activation Notes:'''

*The ODBC drivers are well tested and work well, however, please note that the Commit Support team doesn't provide "pure ODBC" support.

*NEVER use ODBC to modify or delete data; use it for READ purposes only. Modifying data should be done using the Commit API.

*The ODBC Link can be used with your installed version of CommitCRM, and only requires installing an external driver. Before working with the API we recommend that you '''backup the database'''.

Below are the database table names and their meaning:
{| class="wikitable"
|-
! '''CommitCRM Record'''
! '''Database Table Name'''
|-
| Accounts
| Cards
|-
| Tickets
| Tickets
|-
| Charges
| Slips
|-
| Assets
| Assets
|-
| Appointments
| Events
|-
| Tasks
| Events
|-
| History Notes
| NoteBook
|-
| Opportunities
| Opps
|-
| Documents
| Docs
|-
| Knowledge Base
| KBArticles
|}

For the database fields list, please refer to [[Commit_API_Developers_Guide#API_Reference_Manual|API Reference Manual]] section.
You can find detailed instructions for using the ODBC Link in the [[Commit_API_Developers_Guide#Installing_ODBC_Driver|Installing ODBC Driver]] section.

==Installing ODBC Driver==
'''Product Overview''' 
The Advantage ODBC Driver is an ODBC version 3 driver based on the Advantage Client Engine that provides SQL access to the Advantage Database Server. The driver provides
full support for the "Minimum" ODBC SQL grammar specification, as well as many functions
included in the "Core" and "Extended" grammar specifications. When used with the
Advantage Database Server, ODBC users can have the
application stability, performance and reduced network traffic benefits of client/server
architecture.

'''Installation on Windows''' 
Like other ODBC drivers, the Advantage ODBC Driver is installed and managed using the
ODBC Administrator Utility. This utility works with the ODBC Driver Manager to configure
ODBC data sources. At runtime, the ODBC Driver Manager works with available drivers and
their configured data sources. If you have previously installed ODBC drivers, the ODBC Administrator may already be installed on your workstation. The icon for the Administrator is usually found in the Control Panel.

To install the Advantage ODBC Driver:
#Download the ODBC driver version that corresponds with your Advantage SQL Database Server version from the following links: (The Advantage Version number can be seen in the Start Menu Folder Name for Advantage in the CommitCRM Server) '''[http://www.commitcrm.com/downloads/commit-odbc-9-0-0-7.exe ODBC Driver Version 9.0] [http://www.commitcrm.com/downloads/commit-odbc-8-1-0-26.exe ODBC Driver Version 8.1] '''
#Run the Setup program.
#Proceed through the setup windows to complete installation.

'''Data Source Setup for Windows''' 
Once the Advantage ODBC Driver is installed, a data source needs to be configured to use
the Advantage ODBC Driver. The data source is an entry in the Windows Registry. When a
data source is defined for the Advantage Driver, all information specific to the Advantage
Driver and database files is stored under the Data Source entry in the Windows 95/98/ME/
NT/2000/2003/XP Registry. 
The database files and indexes must be stored on your file server, and the Advantage
Database Server must be loaded in order to access the files.

The Data Source settings may be modified at any time. Using the ODBC Administrator, you
may modify the Data Source and Option settings.
For specific information about the screen fields see the Data Source Setup Screen.

'''To Setup the Data Source:'''
#From the ODBC Administrator, click Add.
#Highlight the Advantage SQL ODBC line, and click OK.
#Type a unique data source name. For example, type AdvData. This name is used by applications to reference the data source.
#Specify the database or data dictionary path. Type a valid path name to a mapped drive on the server where the Advantage Database Server is installed or the path and file name of your Advantage Data Dictionary. Click Browse to select a database path or check the Data Dictionary check box and then browse to select a data dictionary file. Note Multiple Advantage data sources may need to be defined for your environment. If different settings are needed for ODBC connections in one application, separate data sources may be required.
#Review the options and change them to your desired setup.
#Once the Options are reviewed and/or altered, click OK to exit and save the settings. The new data source is displayed.
#Click Close to exit the ODBC Administrator.

'''ODBC Data Source Entries for Windows''' 
In Microsoft Windows, the entries are registry settings found on HKEY_CURRENT_USER\Software\ODBC\ODBC.INI\ (your unique data source name) or HKEY_LOCAL_MACHINE\Software\ODBC\ODBC.INI (your unique data source name). Unless specified otherwise, all registry entries can be setup by the Advantage ODBC Driver setup utility. See Data Source Setup for Windows and Data Source Setup Screen for more information. ODBC Data Source Keys.

'''ODBC Data Source Keys''' 
The following ODBC registry is '''required''' for the driver to load:
{| class="wikitable"
|-
! '''Registry Entry'''
! '''Comments'''
|-
| DataDirectory=data path
| 'data path' should be a valid path name for files locations (e.g., x:\data). This path is used to automatically select all tables in the specified directory.
|-
| DefaultType=Advantage
| Sets a certain type of database files to use Advantageproprietary ADT/ADI/ADM files.
|-
| ServerTypes=3
| Allows the Driver to use the remote or local server
|}

The following ODBC registry keys are '''optional''':

{| class="wikitable"
|-
! '''Registry Entry'''
! '''Comments'''
|-
| AdvantageLocking=ON \ OFF
| The default is ON to use the Advantage proprietary locking.
|-
| CharSet=OEM \ ANSI
| The default character collation setting is ANSI. If OEM is specified, Language must be indicated as well.
|-
| Language=USA
| Used if CharSet=OEM.
|-
| Description=String
| This is provided for easier administration.
|-
| Locking=RECORD \ FILE
| Indicates whether updates lock the entire file or the individual records that are updated. The default is RECORD.
|-
| MaxTableCloseCache=n
| N is the number of tables to hold in cache when cursors are opened and closed. The default is 25.
|-
| MemoBlockSize=n
| N is the size of the Advantage memo blocks in tables that are created by the ODBC driver. The default value is 8 for Advantage proprietary table (ADT/ADM).
|-
| Rows=TRUE \ FALSE
| Select whether deleted rows are displayed. If True, deleted rows are displayed. The default is False.
|-
| TrimTrailingSpaces=TRUE \ FALSE
| The default is False. If True is specified, trailing spaces in character fields will be removed prior to returning the values to the application.
|}

==Troubleshooting ODBC in 64 Bit Operating Systems==
The Commit ODBC drivers are mainly distributed for 32-bit operating systems; however, the same drivers are supported on the 64-bit operating systems (I.e. Windows 7 x64), and can be used to retrieve data from the CommitCRM database.

 
===Configuring Data Source in 64-Bit Systems===
When installing the ODBC drivers on 64-bit operating systems, the ODBC drivers may not be displayed in the default ODBC manager in windows control panel. In order to view the 32-bit ODBC manager in a 64-bit operating system, you’ll need to browse to '''%windir%\SysWOW64\odbcad32.exe''' and run the 32 bit ODBC Administrator manually. Once the data source has been configured there, you should be able to select the data source in your 3rd party ODBC programs.

 
=Samples=
The Commit API allows you to add/update the following entities:
*Accounts
*Assets
*Tickets
*Charges
*Appointments
*Tasks
*History Notes
*Opportunities
*Documents
*Knowledge Base Articles

Each API method requires a list of parameters which contain the field names and their values. The field names are the Database field names. You can see each field's name within the application (so you can verify which field you are about to update), by right-clicking the field and selecting Field Settings > Advanced Tab > view the Tech. Rec ID field.

You can view the complete list of database fields in the [[Commit_API_Developers_Guide#API_Reference_Manual|API Reference Manual]] above.

Following are samples for using the API by Email and the Programming API. The samples are basic and provide an easy starting point.

See [[API Code Samples]].

=API Reference Manual=

The API allows you to add/update the following entities:
*Accounts
*Assets
*Tickets
*Charges (and Contract-price Charges)
*Appointments
*Tasks
*History Notes
*Opportunities
*Documents
*Knowledge Base Articles

You can find a detailed listing of the database fields in the [[API Reference Manual]].

=See Also=
*[[API Code Samples]]
*[[API Reference Manual]]
*[[Email Connector|Commit Email Connector]]
*[[API by Email and MSP Integration]]
*[[MSP Integration Setup]]
*[http://www.commitcrm.com/sql_database_server.htm Commit SQL Database (CSD)]
*[[Commit SQL Database Installation Guide | Commit SQL Database (CSD) Installation Guide]]

[[Category:User Manuals]]
[[Category:Integration]]

API Developers Guide

2010-04-07T19:54:31Z

Reno: /* Installing ODBC Driver */

{{usermanuals}}

=Introduction=
CommitCRM provides various tools in order to read/add/update information in the CommitCRM
database. These tools include: Programming API and API by Email for updating the
database, and an ODBC Link for pulling information from the database.
The Commit API provides developers with a set of APIs which allow them to perform
database transactions in order to add and update records in the CommitCRM database. The
API can be used as a Programming API by embedding code which uses the API functions,
or as an API by Email which allows you to send XML formatted emails which will be
processed and executed.

__TOC__

*'''Programming API''' The Commit API provides developers with a set of API functions which can be used in VB, C++, Delphi and any other programming language that lets you use a standard Windows dll file. It provides the ability to create a connection to CommitCRM's database, add new records to the database and update them.

*'''API by Email''' The API by Email allows you to send XML formatted emails which contain database transactions. Commit Email Connector then pulls the incoming XML emails from your POP3 mail server, processes the email and performs the transactions in the XML transaction. XML formatted email gives you an API for the CommitCRM database, which allows you to perform many actions such as linking to external systems, receiving forms submitted from your web site, and more.

*'''ODBC Link''' While the API provides the means for adding and updating information in the database, you should use ODBC Link in order to read information from the database. CommitCRM uses an open database structure and allows other applications to access the database using ODBC (Open Data Base Connectivity) for '''read-only''' purposes. You can use ODBC Link in order to read data from the database and integrate it with an external system (i.e. Crystal reports, or any other application). You may also use the ODBC Link to read Database Record IDs and update existing records. This will be discussed later in this document.

=Glossary=
*'''Commit API (Application Programming Interface)''' - CommitCRM provides an API which allows you to add and update records in the CommitCRM database. The API includes a list of possible actions and parameters.

*'''ODBC Link (Open Data Base Connectivity)''' - ODBC is a function library which provides a common API for ODBC compliant databases. CommitCRM provides an open database and allows other applications to access the database using ODBC for '''read-only''' purposes.

*'''Record''' - Each entity in the CommitCRM database (such as Ticket, Account, Asset, Item, Appointment, Task, etc.) is considered a "record".

*'''Database fields''' - Each record contains a list of fields, each of which holds the record's data.

*'''Transaction''' – All additions or updates to record in the database are done by using a transaction. Each transaction includes the operation you wish to perform, the data type you wish to add/update and the additional parameters (database fields and their values).

*'''Transaction Parameters''' - Each transaction contains the parameters for performing the transaction: record type, list of database fields and a list of the values to be updated in these fields.

*'''External Application''' - This refers to the external program which integrates with CommitCRM in order to update the database. This name should be passed when performing updates to the database, and it will be saved in the CommitCRM record to indicate who performed the changes.

*'''Record ID (REC ID)''' - Each record in CommitCRM has a '''unique Record ID''' which is created when adding the record to the database. Every ID is 20 characters and should be transferred with the API transaction when you need to update an existing record.

=Using Commit API=
Commit API allows you to add and update records in the CommitCRM database, such as
Accounts, Tickets, Assets, Items, Appointments, Tasks and more.

The updates are performed using transactions, where each transaction includes the
operation you wish to perform, the data type you wish to add/update, and any additional
parameters (i.e. record type, database fields and their values).

Every record added to the system is assigned a unique Record ID (REC ID) which is the
database identifier for this record.

The Commit API allows you to perform the following operations.

*'''Add new records''' - if no Record ID is passed in the transaction, the API assumes that this is a new record, adds it to the system and creates a new Record ID for it.

*'''Update existing records''' - if the record ID is passed in the transaction, and the record exists, the system will update the record with the information in the transaction.

In both cases, the system will try to set default values for fields which do not exist in the
incoming transaction. If it fails, the action will fail with an error.

Note that in order to '''read data''' from the CommitCRM database, you should use the ODBC
Link, which provides a read-only link for the CommitCRM database. See more details in
[[#Retrieving data using ODBC|Retrieving data using ODBC]].

==Workflow==
Following is a sample work-flow, which demonstrates the process of adding a new Account, and then adding a new Ticket to this Account, using the Commit API.

Note that the API can return two parameters to the External Application:
#The Commit REC ID - when adding new records to the database, this will contains the new record ID.
#The ExternalTransactionID (relevant for XML transaction only) - In case the external application passes a parameter to be returned with the response, the ExternalTransactionID will be returned as-is to in the response.

The External Application should keep the REC ID which is returned from the API response. This allows you to later update the existing records with new data or add records related to it (such as opening a Ticket under the Account).

[[File:flow.gif|center]]

==Updating existing records==
In order to update an already existing record in the database (e.g. add a Ticket to an
Account, update an Account's phone number, add a new Charge to an existing Ticket,
etc.), you should pass the record's unique identifier to the API so it will update the
existing record rather than create a new Account. The record's unique identifier is
referred to as the Record ID (REC ID).

The Record ID can be obtained in the following ways:
#'''API Response''' (as in the flow above) - You can extract the newly created Record ID from the Email Response when adding new records with the API. This requires the developer to process the API responses, and extract the returning REC ID for each newly added record.
#'''ODBC Link''' - Use the ODBC Link to find relevant records (Accounts, Tickets, etc.), and read all information from the database, including the unique Record ID.
#'''Manually''' - from the Account's Notes tab, at the bottom, right-click the REC ID field and copy it.

Once you have obtained the Record ID you can pass the Record ID as a parameter for the
API and update this record.

=Programming API=
The Programming API allows you access the CommitCRM database and perform transactions
from within a program (using various programming language). This means you can embed
code which accesses the CommitCRM database from within your own application, and add
your own functionality which updates the database.

The programming API executes database transactions. Each transaction uses API methods
provides by the API dll file which is located in the CommitCRM installation. Both the
Programming API and the API by Email use the same dll for performing the transactions.

Note that the API provides the tools needed for adding/updating information in the
database. In order to retrieve data, you should use the ODBC link which allows you to
connect to the database and retrieve data directly from the tables. You can read more
about it in the [[Commit_API_Developers_Guide#ODBC_Data_Retrieval|ODBC Data Retrieval]] section.

You can find more information and samples in the [[API Code Samples]] section.

=API by Email (XML transaction)=
The API by Email operates under the Commit Email Connector module, which
automatically processes incoming emails arriving at a defined public email address. The
Email may contain XML formatted messages which contain API transactions, and provides
a full API to CommitCRM.

The Email Connector pulls incoming emails from your POP3 mail server, and processes the
email. When an email containing XML formatted message is detected, the system analyzes
the XML content of the email and performs the transactions written in the XML. You may
set the Email Connector to send automatic replies in response to XML formatted email.

The API by Email executes database transactions. Each transaction uses API methods
provided by the API dll file which is located in the CommitCRM installation. Both the
Programming API and the API by Email use the same dll for performing the transactions.

Note that the API provides the tools for adding/updating information in the database. In
order to retrieve data, you should use the ODBC link which allows you to connect to the
database and retrieve data directly from the tables. You can read more about it in the
[[Commit_API_Developers_Guide#ODBC_Data_Retrieval|ODBC Data Retrieval]] section.

You can find more information and samples in [[API Code Samples#XML samples|XML samples]].

=ODBC Data Retrieval=
CommitCRM uses an open database and allows other applications to access it using ODBC
(Open Data Base Connectivity) for '''read-only''' purposes. While the API provides the means
for adding and updating information in the database, it is preferred to use ODBC to read
information from the database.

You can use ODBC Link to read data from the database and integrate it with an external
system (i.e. Crystal reports, or any other application). You may also use the ODBC Link in
order to read the Database Record ID and update existing records (see [[Commit_API_Developers_Guide#Updating_existing_records|Updating existing records]]).

'''Activation Notes:'''

*The ODBC drivers are well tested and work well, however, please note that the Commit Support team doesn't provide "pure ODBC" support.

*NEVER use ODBC to modify or delete data; use it for READ purposes only. Modifying data should be done using the Commit API.

*The ODBC Link can be used with your installed version of CommitCRM, and only requires installing an external driver. Before working with the API we recommend that you '''backup the database'''.

Below are the database table names and their meaning:
{| class="wikitable"
|-
! '''CommitCRM Record'''
! '''Database Table Name'''
|-
| Accounts
| Cards
|-
| Tickets
| Tickets
|-
| Charges
| Slips
|-
| Assets
| Assets
|-
| Appointments
| Events
|-
| Tasks
| Events
|-
| History Notes
| NoteBook
|-
| Opportunities
| Opps
|-
| Documents
| Docs
|-
| Knowledge Base
| KBArticles
|}

For the database fields list, please refer to [[Commit_API_Developers_Guide#API_Reference_Manual|API Reference Manual]] section.
You can find detailed instructions for using the ODBC Link in the [[Commit_API_Developers_Guide#Installing_ODBC_Driver|Installing ODBC Driver]] section.

==Installing ODBC Driver==
'''Product Overview''' 
The Advantage ODBC Driver is an ODBC version 3 driver based on the Advantage Client Engine that provides SQL access to the Advantage Database Server. The driver provides
full support for the "Minimum" ODBC SQL grammar specification, as well as many functions
included in the "Core" and "Extended" grammar specifications. When used with the
Advantage Database Server, ODBC users can have the
application stability, performance and reduced network traffic benefits of client/server
architecture.

'''Installation on Windows''' 
Like other ODBC drivers, the Advantage ODBC Driver is installed and managed using the
ODBC Administrator Utility. This utility works with the ODBC Driver Manager to configure
ODBC data sources. At runtime, the ODBC Driver Manager works with available drivers and
their configured data sources. If you have previously installed ODBC drivers, the ODBC Administrator may already be installed on your workstation. The icon for the Administrator is usually found in the Control Panel.

To install the Advantage ODBC Driver:
#Download the ODBC driver version that corresponds with your Advantage SQL Database Server from the following links: (The Advantage Version number can be seen in the Start Menu Folder Name for Advantage in the CommitCRM Server) '''[http://www.commitcrm.com/downloads/commit-odbc-9-0-0-7.exe ODBC Driver Version 9.0] [http://www.commitcrm.com/downloads/commit-odbc-8-1-0-26.exe ODBC Driver Version 8.1] '''
#Run the Setup program.
#Proceed through the setup windows to complete installation.

'''Data Source Setup for Windows''' 
Once the Advantage ODBC Driver is installed, a data source needs to be configured to use
the Advantage ODBC Driver. The data source is an entry in the Windows Registry. When a
data source is defined for the Advantage Driver, all information specific to the Advantage
Driver and database files is stored under the Data Source entry in the Windows 95/98/ME/
NT/2000/2003/XP Registry. 
The database files and indexes must be stored on your file server, and the Advantage
Database Server must be loaded in order to access the files.

The Data Source settings may be modified at any time. Using the ODBC Administrator, you
may modify the Data Source and Option settings.
For specific information about the screen fields see the Data Source Setup Screen.

'''To Setup the Data Source:'''
#From the ODBC Administrator, click Add.
#Highlight the Advantage SQL ODBC line, and click OK.
#Type a unique data source name. For example, type AdvData. This name is used by applications to reference the data source.
#Specify the database or data dictionary path. Type a valid path name to a mapped drive on the server where the Advantage Database Server is installed or the path and file name of your Advantage Data Dictionary. Click Browse to select a database path or check the Data Dictionary check box and then browse to select a data dictionary file. Note Multiple Advantage data sources may need to be defined for your environment. If different settings are needed for ODBC connections in one application, separate data sources may be required.
#Review the options and change them to your desired setup.
#Once the Options are reviewed and/or altered, click OK to exit and save the settings. The new data source is displayed.
#Click Close to exit the ODBC Administrator.

'''ODBC Data Source Entries for Windows''' 
In Microsoft Windows, the entries are registry settings found on HKEY_CURRENT_USER\Software\ODBC\ODBC.INI\ (your unique data source name) or HKEY_LOCAL_MACHINE\Software\ODBC\ODBC.INI (your unique data source name). Unless specified otherwise, all registry entries can be setup by the Advantage ODBC Driver setup utility. See Data Source Setup for Windows and Data Source Setup Screen for more information. ODBC Data Source Keys.

'''ODBC Data Source Keys''' 
The following ODBC registry is '''required''' for the driver to load:
{| class="wikitable"
|-
! '''Registry Entry'''
! '''Comments'''
|-
| DataDirectory=data path
| 'data path' should be a valid path name for files locations (e.g., x:\data). This path is used to automatically select all tables in the specified directory.
|-
| DefaultType=Advantage
| Sets a certain type of database files to use Advantageproprietary ADT/ADI/ADM files.
|-
| ServerTypes=3
| Allows the Driver to use the remote or local server
|}

The following ODBC registry keys are '''optional''':

{| class="wikitable"
|-
! '''Registry Entry'''
! '''Comments'''
|-
| AdvantageLocking=ON \ OFF
| The default is ON to use the Advantage proprietary locking.
|-
| CharSet=OEM \ ANSI
| The default character collation setting is ANSI. If OEM is specified, Language must be indicated as well.
|-
| Language=USA
| Used if CharSet=OEM.
|-
| Description=String
| This is provided for easier administration.
|-
| Locking=RECORD \ FILE
| Indicates whether updates lock the entire file or the individual records that are updated. The default is RECORD.
|-
| MaxTableCloseCache=n
| N is the number of tables to hold in cache when cursors are opened and closed. The default is 25.
|-
| MemoBlockSize=n
| N is the size of the Advantage memo blocks in tables that are created by the ODBC driver. The default value is 8 for Advantage proprietary table (ADT/ADM).
|-
| Rows=TRUE \ FALSE
| Select whether deleted rows are displayed. If True, deleted rows are displayed. The default is False.
|-
| TrimTrailingSpaces=TRUE \ FALSE
| The default is False. If True is specified, trailing spaces in character fields will be removed prior to returning the values to the application.
|}

==Troubleshooting ODBC in 64 Bit Operating Systems==
The Commit ODBC drivers are mainly distributed for 32-bit operating systems; however, the same drivers are supported on the 64-bit operating systems (I.e. Windows 7 x64), and can be used to retrieve data from the CommitCRM database.

 
===Configuring Data Source in 64-Bit Systems===
When installing the ODBC drivers on 64-bit operating systems, the ODBC drivers may not be displayed in the default ODBC manager in windows control panel. In order to view the 32-bit ODBC manager in a 64-bit operating system, you’ll need to browse to '''%windir%\SysWOW64\odbcad32.exe''' and run the 32 bit ODBC Administrator manually. Once the data source has been configured there, you should be able to select the data source in your 3rd party ODBC programs.

 
=Samples=
The Commit API allows you to add/update the following entities:
*Accounts
*Assets
*Tickets
*Charges
*Appointments
*Tasks
*History Notes
*Opportunities
*Documents
*Knowledge Base Articles

Each API method requires a list of parameters which contain the field names and their values. The field names are the Database field names. You can see each field's name within the application (so you can verify which field you are about to update), by right-clicking the field and selecting Field Settings > Advanced Tab > view the Tech. Rec ID field.

You can view the complete list of database fields in the [[Commit_API_Developers_Guide#API_Reference_Manual|API Reference Manual]] above.

Following are samples for using the API by Email and the Programming API. The samples are basic and provide an easy starting point.

See [[API Code Samples]].

=API Reference Manual=

The API allows you to add/update the following entities:
*Accounts
*Assets
*Tickets
*Charges (and Contract-price Charges)
*Appointments
*Tasks
*History Notes
*Opportunities
*Documents
*Knowledge Base Articles

You can find a detailed listing of the database fields in the [[API Reference Manual]].

=See Also=
*[[API Code Samples]]
*[[API Reference Manual]]
*[[Email Connector|Commit Email Connector]]
*[[API by Email and MSP Integration]]
*[[MSP Integration Setup]]
*[http://www.commitcrm.com/sql_database_server.htm Commit SQL Database (CSD)]
*[[Commit SQL Database Installation Guide | Commit SQL Database (CSD) Installation Guide]]

[[Category:User Manuals]]
[[Category:Integration]]

API Developers Guide

2010-04-07T19:45:53Z

Reno: Undo revision 3975 by Reno (Talk)

{{usermanuals}}

=Introduction=
CommitCRM provides various tools in order to read/add/update information in the CommitCRM
database. These tools include: Programming API and API by Email for updating the
database, and an ODBC Link for pulling information from the database.
The Commit API provides developers with a set of APIs which allow them to perform
database transactions in order to add and update records in the CommitCRM database. The
API can be used as a Programming API by embedding code which uses the API functions,
or as an API by Email which allows you to send XML formatted emails which will be
processed and executed.

__TOC__

*'''Programming API''' The Commit API provides developers with a set of API functions which can be used in VB, C++, Delphi and any other programming language that lets you use a standard Windows dll file. It provides the ability to create a connection to CommitCRM's database, add new records to the database and update them.

*'''API by Email''' The API by Email allows you to send XML formatted emails which contain database transactions. Commit Email Connector then pulls the incoming XML emails from your POP3 mail server, processes the email and performs the transactions in the XML transaction. XML formatted email gives you an API for the CommitCRM database, which allows you to perform many actions such as linking to external systems, receiving forms submitted from your web site, and more.

*'''ODBC Link''' While the API provides the means for adding and updating information in the database, you should use ODBC Link in order to read information from the database. CommitCRM uses an open database structure and allows other applications to access the database using ODBC (Open Data Base Connectivity) for '''read-only''' purposes. You can use ODBC Link in order to read data from the database and integrate it with an external system (i.e. Crystal reports, or any other application). You may also use the ODBC Link to read Database Record IDs and update existing records. This will be discussed later in this document.

=Glossary=
*'''Commit API (Application Programming Interface)''' - CommitCRM provides an API which allows you to add and update records in the CommitCRM database. The API includes a list of possible actions and parameters.

*'''ODBC Link (Open Data Base Connectivity)''' - ODBC is a function library which provides a common API for ODBC compliant databases. CommitCRM provides an open database and allows other applications to access the database using ODBC for '''read-only''' purposes.

*'''Record''' - Each entity in the CommitCRM database (such as Ticket, Account, Asset, Item, Appointment, Task, etc.) is considered a "record".

*'''Database fields''' - Each record contains a list of fields, each of which holds the record's data.

*'''Transaction''' – All additions or updates to record in the database are done by using a transaction. Each transaction includes the operation you wish to perform, the data type you wish to add/update and the additional parameters (database fields and their values).

*'''Transaction Parameters''' - Each transaction contains the parameters for performing the transaction: record type, list of database fields and a list of the values to be updated in these fields.

*'''External Application''' - This refers to the external program which integrates with CommitCRM in order to update the database. This name should be passed when performing updates to the database, and it will be saved in the CommitCRM record to indicate who performed the changes.

*'''Record ID (REC ID)''' - Each record in CommitCRM has a '''unique Record ID''' which is created when adding the record to the database. Every ID is 20 characters and should be transferred with the API transaction when you need to update an existing record.

=Using Commit API=
Commit API allows you to add and update records in the CommitCRM database, such as
Accounts, Tickets, Assets, Items, Appointments, Tasks and more.

The updates are performed using transactions, where each transaction includes the
operation you wish to perform, the data type you wish to add/update, and any additional
parameters (i.e. record type, database fields and their values).

Every record added to the system is assigned a unique Record ID (REC ID) which is the
database identifier for this record.

The Commit API allows you to perform the following operations.

*'''Add new records''' - if no Record ID is passed in the transaction, the API assumes that this is a new record, adds it to the system and creates a new Record ID for it.

*'''Update existing records''' - if the record ID is passed in the transaction, and the record exists, the system will update the record with the information in the transaction.

In both cases, the system will try to set default values for fields which do not exist in the
incoming transaction. If it fails, the action will fail with an error.

Note that in order to '''read data''' from the CommitCRM database, you should use the ODBC
Link, which provides a read-only link for the CommitCRM database. See more details in
[[#Retrieving data using ODBC|Retrieving data using ODBC]].

==Workflow==
Following is a sample work-flow, which demonstrates the process of adding a new Account, and then adding a new Ticket to this Account, using the Commit API.

Note that the API can return two parameters to the External Application:
#The Commit REC ID - when adding new records to the database, this will contains the new record ID.
#The ExternalTransactionID (relevant for XML transaction only) - In case the external application passes a parameter to be returned with the response, the ExternalTransactionID will be returned as-is to in the response.

The External Application should keep the REC ID which is returned from the API response. This allows you to later update the existing records with new data or add records related to it (such as opening a Ticket under the Account).

[[File:flow.gif|center]]

==Updating existing records==
In order to update an already existing record in the database (e.g. add a Ticket to an
Account, update an Account's phone number, add a new Charge to an existing Ticket,
etc.), you should pass the record's unique identifier to the API so it will update the
existing record rather than create a new Account. The record's unique identifier is
referred to as the Record ID (REC ID).

The Record ID can be obtained in the following ways:
#'''API Response''' (as in the flow above) - You can extract the newly created Record ID from the Email Response when adding new records with the API. This requires the developer to process the API responses, and extract the returning REC ID for each newly added record.
#'''ODBC Link''' - Use the ODBC Link to find relevant records (Accounts, Tickets, etc.), and read all information from the database, including the unique Record ID.
#'''Manually''' - from the Account's Notes tab, at the bottom, right-click the REC ID field and copy it.

Once you have obtained the Record ID you can pass the Record ID as a parameter for the
API and update this record.

=Programming API=
The Programming API allows you access the CommitCRM database and perform transactions
from within a program (using various programming language). This means you can embed
code which accesses the CommitCRM database from within your own application, and add
your own functionality which updates the database.

The programming API executes database transactions. Each transaction uses API methods
provides by the API dll file which is located in the CommitCRM installation. Both the
Programming API and the API by Email use the same dll for performing the transactions.

Note that the API provides the tools needed for adding/updating information in the
database. In order to retrieve data, you should use the ODBC link which allows you to
connect to the database and retrieve data directly from the tables. You can read more
about it in the [[Commit_API_Developers_Guide#ODBC_Data_Retrieval|ODBC Data Retrieval]] section.

You can find more information and samples in the [[API Code Samples]] section.

=API by Email (XML transaction)=
The API by Email operates under the Commit Email Connector module, which
automatically processes incoming emails arriving at a defined public email address. The
Email may contain XML formatted messages which contain API transactions, and provides
a full API to CommitCRM.

The Email Connector pulls incoming emails from your POP3 mail server, and processes the
email. When an email containing XML formatted message is detected, the system analyzes
the XML content of the email and performs the transactions written in the XML. You may
set the Email Connector to send automatic replies in response to XML formatted email.

The API by Email executes database transactions. Each transaction uses API methods
provided by the API dll file which is located in the CommitCRM installation. Both the
Programming API and the API by Email use the same dll for performing the transactions.

Note that the API provides the tools for adding/updating information in the database. In
order to retrieve data, you should use the ODBC link which allows you to connect to the
database and retrieve data directly from the tables. You can read more about it in the
[[Commit_API_Developers_Guide#ODBC_Data_Retrieval|ODBC Data Retrieval]] section.

You can find more information and samples in [[API Code Samples#XML samples|XML samples]].

=ODBC Data Retrieval=
CommitCRM uses an open database and allows other applications to access it using ODBC
(Open Data Base Connectivity) for '''read-only''' purposes. While the API provides the means
for adding and updating information in the database, it is preferred to use ODBC to read
information from the database.

You can use ODBC Link to read data from the database and integrate it with an external
system (i.e. Crystal reports, or any other application). You may also use the ODBC Link in
order to read the Database Record ID and update existing records (see [[Commit_API_Developers_Guide#Updating_existing_records|Updating existing records]]).

'''Activation Notes:'''

*The ODBC drivers are well tested and work well, however, please note that the Commit Support team doesn't provide "pure ODBC" support.

*NEVER use ODBC to modify or delete data; use it for READ purposes only. Modifying data should be done using the Commit API.

*The ODBC Link can be used with your installed version of CommitCRM, and only requires installing an external driver. Before working with the API we recommend that you '''backup the database'''.

Below are the database table names and their meaning:
{| class="wikitable"
|-
! '''CommitCRM Record'''
! '''Database Table Name'''
|-
| Accounts
| Cards
|-
| Tickets
| Tickets
|-
| Charges
| Slips
|-
| Assets
| Assets
|-
| Appointments
| Events
|-
| Tasks
| Events
|-
| History Notes
| NoteBook
|-
| Opportunities
| Opps
|-
| Documents
| Docs
|-
| Knowledge Base
| KBArticles
|}

For the database fields list, please refer to [[Commit_API_Developers_Guide#API_Reference_Manual|API Reference Manual]] section.
You can find detailed instructions for using the ODBC Link in the [[Commit_API_Developers_Guide#Installing_ODBC_Driver|Installing ODBC Driver]] section.

==Installing ODBC Driver==
'''Product Overview''' 
The Advantage ODBC Driver is an ODBC version 3 driver based on the Advantage Client Engine that provides SQL access to the Advantage Database Server. The driver provides
full support for the "Minimum" ODBC SQL grammar specification, as well as many functions
included in the "Core" and "Extended" grammar specifications. When used with the
Advantage Database Server, ODBC users can have the
application stability, performance and reduced network traffic benefits of client/server
architecture.

'''Installation on Windows''' 
Like other ODBC drivers, the Advantage ODBC Driver is installed and managed using the
ODBC Administrator Utility. This utility works with the ODBC Driver Manager to configure
ODBC data sources. At runtime, the ODBC Driver Manager works with available drivers and
their configured data sources. If you have previously installed ODBC drivers, the ODBC Administrator may already be installed on your workstation. The icon for the Administrator is usually found in the Control Panel.

To install the Advantage ODBC Driver:
#[http://www.commitcrm.com/downloads/commit-odbc-8-1-0-26.exe Click here] to download the Advantage ODBC setup program.
#Run the Setup program.
#Proceed through the setup windows to complete installation.

'''Data Source Setup for Windows''' 
Once the Advantage ODBC Driver is installed, a data source needs to be configured to use
the Advantage ODBC Driver. The data source is an entry in the Windows Registry. When a
data source is defined for the Advantage Driver, all information specific to the Advantage
Driver and database files is stored under the Data Source entry in the Windows 95/98/ME/
NT/2000/2003/XP Registry. 
The database files and indexes must be stored on your file server, and the Advantage
Database Server must be loaded in order to access the files.

The Data Source settings may be modified at any time. Using the ODBC Administrator, you
may modify the Data Source and Option settings.
For specific information about the screen fields see the Data Source Setup Screen.

'''To Setup the Data Source:'''
#From the ODBC Administrator, click Add.
#Highlight the Advantage SQL ODBC line, and click OK.
#Type a unique data source name. For example, type AdvData. This name is used by applications to reference the data source.
#Specify the database or data dictionary path. Type a valid path name to a mapped drive on the server where the Advantage Database Server is installed or the path and file name of your Advantage Data Dictionary. Click Browse to select a database path or check the Data Dictionary check box and then browse to select a data dictionary file. Note Multiple Advantage data sources may need to be defined for your environment. If different settings are needed for ODBC connections in one application, separate data sources may be required.
#Review the options and change them to your desired setup.
#Once the Options are reviewed and/or altered, click OK to exit and save the settings. The new data source is displayed.
#Click Close to exit the ODBC Administrator.

'''ODBC Data Source Entries for Windows''' 
In Microsoft Windows, the entries are registry settings found on HKEY_CURRENT_USER\Software\ODBC\ODBC.INI\ (your unique data source name) or HKEY_LOCAL_MACHINE\Software\ODBC\ODBC.INI (your unique data source name). Unless specified otherwise, all registry entries can be setup by the Advantage ODBC Driver setup utility. See Data Source Setup for Windows and Data Source Setup Screen for more information. ODBC Data Source Keys.

'''ODBC Data Source Keys''' 
The following ODBC registry is '''required''' for the driver to load:
{| class="wikitable"
|-
! '''Registry Entry'''
! '''Comments'''
|-
| DataDirectory=data path
| 'data path' should be a valid path name for files locations (e.g., x:\data). This path is used to automatically select all tables in the specified directory.
|-
| DefaultType=Advantage
| Sets a certain type of database files to use Advantageproprietary ADT/ADI/ADM files.
|-
| ServerTypes=3
| Allows the Driver to use the remote or local server
|}

The following ODBC registry keys are '''optional''':

{| class="wikitable"
|-
! '''Registry Entry'''
! '''Comments'''
|-
| AdvantageLocking=ON \ OFF
| The default is ON to use the Advantage proprietary locking.
|-
| CharSet=OEM \ ANSI
| The default character collation setting is ANSI. If OEM is specified, Language must be indicated as well.
|-
| Language=USA
| Used if CharSet=OEM.
|-
| Description=String
| This is provided for easier administration.
|-
| Locking=RECORD \ FILE
| Indicates whether updates lock the entire file or the individual records that are updated. The default is RECORD.
|-
| MaxTableCloseCache=n
| N is the number of tables to hold in cache when cursors are opened and closed. The default is 25.
|-
| MemoBlockSize=n
| N is the size of the Advantage memo blocks in tables that are created by the ODBC driver. The default value is 8 for Advantage proprietary table (ADT/ADM).
|-
| Rows=TRUE \ FALSE
| Select whether deleted rows are displayed. If True, deleted rows are displayed. The default is False.
|-
| TrimTrailingSpaces=TRUE \ FALSE
| The default is False. If True is specified, trailing spaces in character fields will be removed prior to returning the values to the application.
|}

==Troubleshooting ODBC in 64 Bit Operating Systems==
The Commit ODBC drivers are mainly distributed for 32-bit operating systems; however, the same drivers are supported on the 64-bit operating systems (I.e. Windows 7 x64), and can be used to retrieve data from the CommitCRM database.

 
===Configuring Data Source in 64-Bit Systems===
When installing the ODBC drivers on 64-bit operating systems, the ODBC drivers may not be displayed in the default ODBC manager in windows control panel. In order to view the 32-bit ODBC manager in a 64-bit operating system, you’ll need to browse to '''%windir%\SysWOW64\odbcad32.exe''' and run the 32 bit ODBC Administrator manually. Once the data source has been configured there, you should be able to select the data source in your 3rd party ODBC programs.

 
=Samples=
The Commit API allows you to add/update the following entities:
*Accounts
*Assets
*Tickets
*Charges
*Appointments
*Tasks
*History Notes
*Opportunities
*Documents
*Knowledge Base Articles

Each API method requires a list of parameters which contain the field names and their values. The field names are the Database field names. You can see each field's name within the application (so you can verify which field you are about to update), by right-clicking the field and selecting Field Settings > Advanced Tab > view the Tech. Rec ID field.

You can view the complete list of database fields in the [[Commit_API_Developers_Guide#API_Reference_Manual|API Reference Manual]] above.

Following are samples for using the API by Email and the Programming API. The samples are basic and provide an easy starting point.

See [[API Code Samples]].

=API Reference Manual=

The API allows you to add/update the following entities:
*Accounts
*Assets
*Tickets
*Charges (and Contract-price Charges)
*Appointments
*Tasks
*History Notes
*Opportunities
*Documents
*Knowledge Base Articles

You can find a detailed listing of the database fields in the [[API Reference Manual]].

=See Also=
*[[API Code Samples]]
*[[API Reference Manual]]
*[[Email Connector|Commit Email Connector]]
*[[API by Email and MSP Integration]]
*[[MSP Integration Setup]]
*[http://www.commitcrm.com/sql_database_server.htm Commit SQL Database (CSD)]
*[[Commit SQL Database Installation Guide | Commit SQL Database (CSD) Installation Guide]]

[[Category:User Manuals]]
[[Category:Integration]]

SQL Database Troubleshooting

2010-04-07T19:44:38Z

Reno: /* Important Note For Users that Use our ODBC API */

__TOC__

 
==Problem Description==
When setting up the Commit SQL Database (CSD), the client PCs running the CommitCRM client application cannot connect to the Commit SQL Database, and an error is displayed saying:

Procedure halted due to data server error. Verify server is operating and this computer has access to the server folder. (C:\Commit\DB)

 
[[File:Error.jpg]]

 

==Explanation==
This problem occurs when the client PCs try to connect to the Commit SQL Database, which is installed on your server, and it doesn’t “answer” to their connection requests.
By default, CommitCRM clients send a UDP broadcast message on the network, checking where the Commit SQL Database server is found; if found the server answers with the relevant information for the client to connect to it (IP, Port, etc.). This handshake process may require allowing UDP broadcasts inside you LAN. Usually this does not require any special setup; however, with some advanced network security settings it may be required.
It is also required that the Commit SQL Database, which runs on your server as a Windows service called Advantage Database Server, will be up and running and be allowed to communicate with your LAN.

 

==Troubleshooting Steps==
In order to assure the Commit SQL Database can communicate with the CommitCRM clients, we ask that you cover the following steps.

*'''Please remember to test the Commit SQL Database communications again after applying each step, and if the issue persists, then the next step should be applied.'''

===Advantage Server===
*Verfiy the Advantage Database Server service is started on your server. For installation instructions click [[Commit_SQL_Database_Installation_Guide|here]] or [[Commit_SQL_Database_for_Trial_Users|here]] if your are using a trial copy of CSD.

*'''Please restart all Commit services, and retest communications by loading a CommitCRM Client application from another computer.'''

===DEP – Data Execution Prevention===
*Please ensure that if using DEP on the server, where Commit SQL Database (aka, Advantage Database Server) is installed, it should be configured to allow data execution for '''ADS.exe''', by default located in the following folder '''C:\Program Files\Extended Systems\Advantage 9007\Server'''. This file is the Commit SQL Database / Advantage Database Server Windows service executable file and therefore should be allowed, or else DEP may isolate the CSD software from communicating with the CommitCRM client applications.

*'''Please restart the Advantage service & all Commit services, and retest communications by loading a CommitCRM Client application from another computer.'''

 

===Firewall - Windows or any other installed Firewall===
*Make sure that your software firewall allows the Advantage port through the firewall (Advantage prot information can be adjusted from '''Start Menu > Programs > Advantage Database Server 9.0 > Advantage Configuration Utility > Configuration Utility tab > Communications tab'''). Also, make sure that no special UDP restrictions are activated on the CommitCRM server.
*If advanced firewall restrictions are configured, please verify that an exception has been placed in the firewall, so that the software may communicate with the network, as well as allowing UDP traffic through the firewall.

*'''Please restart the Advantage service & all Commit services, and retest communications by loading a CommitCRM Client application from another computer.'''

 

===ADS.ini – Server Locator===
*The CommitCRM client's way of finding the Commit SQL Database Server fails. In order for the client to detect where the server is running it broadcasts a UDP message and asks for the server to answer. When the server answers the client knows the server IP and can communicate with it.
*On your server, you can run the Advantage Configuration Utility ('''Start Menu > Programs > Advantage Database Server 9.0 > Advantage Configuration Utility > Configuration Utility tab > Communications tab'''). Using it you can find the Port number which is used for communicating with the clients. When adjusting the CSD ports, you can use any port you like, as long as the port is not being used by any other software.

 
[[File:Communicationstab.jpg]]
 
 
As explained in the previous steps, you should make sure that the Windows firewall on each client on your LAN allows communication with the server for this port. Verifying this will allow communication between the CommitCRM client and Commit SQL Database on the server.
 
 
However, in some cases this is not enough. As explained above, a discovery process takes place when the client loads, trying to find the server... It is possible that your Windows firewall blocks this discovery process even if the port is allowed.
 
 
Therefore, in case you enabled the port on each client (using the firewall settings window) and CommitCRM client still doesn't load, you should continue with the following ('''do not continue with this before testing whether allowing the port has solved the issue'''):

Under the '''<server>\Commit\LastVer'''  folder, create a text file called '''ADS.INI'''
Open this file in Notepad and add the following settings:

'''[MYSERVER] LAN_IP=192.168.0.1 LAN_PORT=2001 ''' 
''IMPORTANT NOTES'':
*Replace '''MYSERVER''' with the name of '''YOUR server'''
*Replace the '''192.168.0.1''' IP address with the '''LOCAL IP address of your server'''.
*Replace the port number '''2001 '''to the one used for Commit SQL Database in your setup ('''this can be viewed by running Advantage Configuration Utility on your server, look for the port in use for your LAN''').

After adding the relevant settings, save the file and then try to run CommitCRM client.
This file tells the CommitCRM client what the server IP is and what port to use and therefore no discovery process is required, avoiding the broadcast stage.

Please remember that in case you ever change the IP of your server on your LAN, you should make sure to update this file again to reflect the change. This is why we usually recommend on allowing the broadcast rather than using this hard-coded method of communication; however, in some configurations it doesn’t work and using an ADS.ini file is mandatory.

*'''Please restart the Advantage service & all Commit services, and retest communications by loading a CommitCRM Client application from another computer.'''
 
 

===ADS.ini – Server Locator (Supplemental)===
*If the Ads.ini file does not correct the issue, then we suggest that '''changing the Server hostname reference''' in ADS.ini to the '''server IP address [192.168.x.x]''' will correct this behavior. (Remember to restart Advantage Service each time ADS.ini is adjusted)
For example:
'''[192.168.0.1] LAN_IP=192.168.0.1 LAN_PORT=2001 '''
''IMPORTANT NOTE:''
*Please replace the ServerName (between the brackets) with '''the servers IP adress''', as displayed in the example above.

*'''Please restart the Advantage service & all Commit services, and retest communications by loading a CommitCRM Client application from another computer.'''

 
====Important Note For Users that Use our ODBC API====
I some cases your system may still present an error message regarding failure of the Discovery process (Advantage Error 6320) when trying to access to the CommitCRM database using an ODBC connection, even after the ADS.ini file has resolved the issues with CommitCRM clients being able to discover the Advantage server. The following solution should resolve this issue as long as the following conditions are met:

* You use the Commit SQL Database (aka, Advantage Database Server on your server) and ODBC.

* The ADS.ini file succeeded in logging in the CommitCRM Software Applications (Clients).

* When using applications you developed with ODBC you receive a message regarding Database Discovery Failure (Error code 6320).

If all of the above prerequisites exist, you should copy the ADS.ini file you prepared from the CommitCRM server folder into the following folder on each the affected workstation:

* '''%Windir%\system32'''

This folder usually translates to: '''C:\Windows\system32'''

'''Note:''' To open these folders on your PC you can paste the paths listed above into a Windows Run dialog box, or into any Windows Explorer path.

 

==Recurring issues after Rebooting the CommitCRM Server Machine==
The CommitCRM database chooses its database mode upon the first concurrent connection to the system. If a client application, or Commit Addon Service (Such as '''CommmitWebInterface''' or '''CommitServer''')service is already loaded and connected to the server before the Advantage Database Server service finishes loading, then all subsequent connections will be rejected since the prior connection to the database would not allow the Advantage Database Server service full control over the database.

Typical characteristics of this type of problem are repeated manual attention needed to properly connect Advantage Database Server to CommitCRM after rebooting, and restarting the Advantage Database Server service.
To verify this is the issue, please follow these steps:
#Stop any '''Commit Services''' installed in the CommitCRM server.
#Verify no other computers are running CommitCRM.
#Restart the '''Advantage Database Server''' Service.
#Once the '''Advantage Database Server''' service has started, Try Logging in with one client on the '''server machine'''.
#Check the CommitCRM window title to see if '''SQL''' is printed next to your username.
#If successful, Start '''Commit Services'''.

If this process was successful, this is because the '''Commit Services loaded before Advantage Database Server did''', locking Advantage Database Server out of the CommitCRM database. To permanently resolve this behavior, manual rules will''' need to be created''' in order to ensure that The Commit Services '''do not try to load without Advantage Database Server being started'''.

 
===Adding Service Dependency Rules===
Now that CommitCRM depends on the Advantage Database Server Database service, the Commit Services (CommitWebInterface & CommitServer) also need the Advantage Database Server server to to be up before they try to load.
To set these services to be dependent on the Advantage Database Server Service, follow these steps:
# Backup your current registry settings.
# Run '''regedit''' to open your registry.
# Navigate to '''HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services''' and locate the '''CommitWebInterface/CommitServer''' services that you need to set a dependency for.
# Open the '''DependOnService''' key on the right side. If the selected service does not have a '''DependOnService''' key, then create one by right-clicking and selecting '''New > Multi-String Value'''.
# In the '''value''' field, enter '''Advantage Database Server'''.
# Click OK, close your registry and restart your machine.

 

==See Also==
*[[Commit_SQL_Database_Installation_Guide|Commit SQL Database Installation Guide]]
*[[Commit_SQL_Database_for_Trial_Users|Commit SQL Database for Trial Users]]
[[Category:Troubleshooting]]

SQL Database Troubleshooting

2010-04-07T19:42:18Z

Reno: /* Important Note For ODBC Users */

__TOC__

 
==Problem Description==
When setting up the Commit SQL Database (CSD), the client PCs running the CommitCRM client application cannot connect to the Commit SQL Database, and an error is displayed saying:

Procedure halted due to data server error. Verify server is operating and this computer has access to the server folder. (C:\Commit\DB)

 
[[File:Error.jpg]]

 

==Explanation==
This problem occurs when the client PCs try to connect to the Commit SQL Database, which is installed on your server, and it doesn’t “answer” to their connection requests.
By default, CommitCRM clients send a UDP broadcast message on the network, checking where the Commit SQL Database server is found; if found the server answers with the relevant information for the client to connect to it (IP, Port, etc.). This handshake process may require allowing UDP broadcasts inside you LAN. Usually this does not require any special setup; however, with some advanced network security settings it may be required.
It is also required that the Commit SQL Database, which runs on your server as a Windows service called Advantage Database Server, will be up and running and be allowed to communicate with your LAN.

 

==Troubleshooting Steps==
In order to assure the Commit SQL Database can communicate with the CommitCRM clients, we ask that you cover the following steps.

*'''Please remember to test the Commit SQL Database communications again after applying each step, and if the issue persists, then the next step should be applied.'''

===Advantage Server===
*Verfiy the Advantage Database Server service is started on your server. For installation instructions click [[Commit_SQL_Database_Installation_Guide|here]] or [[Commit_SQL_Database_for_Trial_Users|here]] if your are using a trial copy of CSD.

*'''Please restart all Commit services, and retest communications by loading a CommitCRM Client application from another computer.'''

===DEP – Data Execution Prevention===
*Please ensure that if using DEP on the server, where Commit SQL Database (aka, Advantage Database Server) is installed, it should be configured to allow data execution for '''ADS.exe''', by default located in the following folder '''C:\Program Files\Extended Systems\Advantage 9007\Server'''. This file is the Commit SQL Database / Advantage Database Server Windows service executable file and therefore should be allowed, or else DEP may isolate the CSD software from communicating with the CommitCRM client applications.

*'''Please restart the Advantage service & all Commit services, and retest communications by loading a CommitCRM Client application from another computer.'''

 

===Firewall - Windows or any other installed Firewall===
*Make sure that your software firewall allows the Advantage port through the firewall (Advantage prot information can be adjusted from '''Start Menu > Programs > Advantage Database Server 9.0 > Advantage Configuration Utility > Configuration Utility tab > Communications tab'''). Also, make sure that no special UDP restrictions are activated on the CommitCRM server.
*If advanced firewall restrictions are configured, please verify that an exception has been placed in the firewall, so that the software may communicate with the network, as well as allowing UDP traffic through the firewall.

*'''Please restart the Advantage service & all Commit services, and retest communications by loading a CommitCRM Client application from another computer.'''

 

===ADS.ini – Server Locator===
*The CommitCRM client's way of finding the Commit SQL Database Server fails. In order for the client to detect where the server is running it broadcasts a UDP message and asks for the server to answer. When the server answers the client knows the server IP and can communicate with it.
*On your server, you can run the Advantage Configuration Utility ('''Start Menu > Programs > Advantage Database Server 9.0 > Advantage Configuration Utility > Configuration Utility tab > Communications tab'''). Using it you can find the Port number which is used for communicating with the clients. When adjusting the CSD ports, you can use any port you like, as long as the port is not being used by any other software.

 
[[File:Communicationstab.jpg]]
 
 
As explained in the previous steps, you should make sure that the Windows firewall on each client on your LAN allows communication with the server for this port. Verifying this will allow communication between the CommitCRM client and Commit SQL Database on the server.
 
 
However, in some cases this is not enough. As explained above, a discovery process takes place when the client loads, trying to find the server... It is possible that your Windows firewall blocks this discovery process even if the port is allowed.
 
 
Therefore, in case you enabled the port on each client (using the firewall settings window) and CommitCRM client still doesn't load, you should continue with the following ('''do not continue with this before testing whether allowing the port has solved the issue'''):

Under the '''<server>\Commit\LastVer'''  folder, create a text file called '''ADS.INI'''
Open this file in Notepad and add the following settings:

'''[MYSERVER] LAN_IP=192.168.0.1 LAN_PORT=2001 ''' 
''IMPORTANT NOTES'':
*Replace '''MYSERVER''' with the name of '''YOUR server'''
*Replace the '''192.168.0.1''' IP address with the '''LOCAL IP address of your server'''.
*Replace the port number '''2001 '''to the one used for Commit SQL Database in your setup ('''this can be viewed by running Advantage Configuration Utility on your server, look for the port in use for your LAN''').

After adding the relevant settings, save the file and then try to run CommitCRM client.
This file tells the CommitCRM client what the server IP is and what port to use and therefore no discovery process is required, avoiding the broadcast stage.

Please remember that in case you ever change the IP of your server on your LAN, you should make sure to update this file again to reflect the change. This is why we usually recommend on allowing the broadcast rather than using this hard-coded method of communication; however, in some configurations it doesn’t work and using an ADS.ini file is mandatory.

*'''Please restart the Advantage service & all Commit services, and retest communications by loading a CommitCRM Client application from another computer.'''
 
 

===ADS.ini – Server Locator (Supplemental)===
*If the Ads.ini file does not correct the issue, then we suggest that '''changing the Server hostname reference''' in ADS.ini to the '''server IP address [192.168.x.x]''' will correct this behavior. (Remember to restart Advantage Service each time ADS.ini is adjusted)
For example:
'''[192.168.0.1] LAN_IP=192.168.0.1 LAN_PORT=2001 '''
''IMPORTANT NOTE:''
*Please replace the ServerName (between the brackets) with '''the servers IP adress''', as displayed in the example above.

*'''Please restart the Advantage service & all Commit services, and retest communications by loading a CommitCRM Client application from another computer.'''

 
====Important Note For Users that Use our ODBC API====
I some cases your system may still present an error message regarding failure of the Discovery process (Advantage Error 6320) when trying to access to the CommitCRM database using an ODBC connection, even after the ADS.ini file has resolved the issues with CommitCRM clients being able to discover the Advantage server. The following solution should resolve this issue as long as the following conditions are met:

* You use the Commit SQL Database (aka, Advantage Database Server on your server) and ODBC.

* The ADS.ini file succeeded in logging in the CommitCRM Software Applications (Clients).

* When using applications you developed with ODBC you receive a message regarding Database Discovery Failure (Error code 6320).

If all of the above prerequisites exist, you should copy the ADS.ini file you prepared from the CommitCRM server folder into the following folder on each the affected workstation:

* %Windir%\system32

This folder usually translates to: '''C:\Windows\system32'''

'''Note:''' To open these folders on your PC you can paste the paths listed above into a Windows Run dialog box, or into any Windows Explorer path.

 

==Recurring issues after Rebooting the CommitCRM Server Machine==
The CommitCRM database chooses its database mode upon the first concurrent connection to the system. If a client application, or Commit Addon Service (Such as '''CommmitWebInterface''' or '''CommitServer''')service is already loaded and connected to the server before the Advantage Database Server service finishes loading, then all subsequent connections will be rejected since the prior connection to the database would not allow the Advantage Database Server service full control over the database.

Typical characteristics of this type of problem are repeated manual attention needed to properly connect Advantage Database Server to CommitCRM after rebooting, and restarting the Advantage Database Server service.
To verify this is the issue, please follow these steps:
#Stop any '''Commit Services''' installed in the CommitCRM server.
#Verify no other computers are running CommitCRM.
#Restart the '''Advantage Database Server''' Service.
#Once the '''Advantage Database Server''' service has started, Try Logging in with one client on the '''server machine'''.
#Check the CommitCRM window title to see if '''SQL''' is printed next to your username.
#If successful, Start '''Commit Services'''.

If this process was successful, this is because the '''Commit Services loaded before Advantage Database Server did''', locking Advantage Database Server out of the CommitCRM database. To permanently resolve this behavior, manual rules will''' need to be created''' in order to ensure that The Commit Services '''do not try to load without Advantage Database Server being started'''.

 
===Adding Service Dependency Rules===
Now that CommitCRM depends on the Advantage Database Server Database service, the Commit Services (CommitWebInterface & CommitServer) also need the Advantage Database Server server to to be up before they try to load.
To set these services to be dependent on the Advantage Database Server Service, follow these steps:
# Backup your current registry settings.
# Run '''regedit''' to open your registry.
# Navigate to '''HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services''' and locate the '''CommitWebInterface/CommitServer''' services that you need to set a dependency for.
# Open the '''DependOnService''' key on the right side. If the selected service does not have a '''DependOnService''' key, then create one by right-clicking and selecting '''New > Multi-String Value'''.
# In the '''value''' field, enter '''Advantage Database Server'''.
# Click OK, close your registry and restart your machine.

 

==See Also==
*[[Commit_SQL_Database_Installation_Guide|Commit SQL Database Installation Guide]]
*[[Commit_SQL_Database_for_Trial_Users|Commit SQL Database for Trial Users]]
[[Category:Troubleshooting]]

API Developers Guide

2010-04-07T19:26:48Z

Reno: /* Installing ODBC Driver */

{{usermanuals}}

=Introduction=
CommitCRM provides various tools in order to read/add/update information in the CommitCRM
database. These tools include: Programming API and API by Email for updating the
database, and an ODBC Link for pulling information from the database.
The Commit API provides developers with a set of APIs which allow them to perform
database transactions in order to add and update records in the CommitCRM database. The
API can be used as a Programming API by embedding code which uses the API functions,
or as an API by Email which allows you to send XML formatted emails which will be
processed and executed.

__TOC__

*'''Programming API''' The Commit API provides developers with a set of API functions which can be used in VB, C++, Delphi and any other programming language that lets you use a standard Windows dll file. It provides the ability to create a connection to CommitCRM's database, add new records to the database and update them.

*'''API by Email''' The API by Email allows you to send XML formatted emails which contain database transactions. Commit Email Connector then pulls the incoming XML emails from your POP3 mail server, processes the email and performs the transactions in the XML transaction. XML formatted email gives you an API for the CommitCRM database, which allows you to perform many actions such as linking to external systems, receiving forms submitted from your web site, and more.

*'''ODBC Link''' While the API provides the means for adding and updating information in the database, you should use ODBC Link in order to read information from the database. CommitCRM uses an open database structure and allows other applications to access the database using ODBC (Open Data Base Connectivity) for '''read-only''' purposes. You can use ODBC Link in order to read data from the database and integrate it with an external system (i.e. Crystal reports, or any other application). You may also use the ODBC Link to read Database Record IDs and update existing records. This will be discussed later in this document.

=Glossary=
*'''Commit API (Application Programming Interface)''' - CommitCRM provides an API which allows you to add and update records in the CommitCRM database. The API includes a list of possible actions and parameters.

*'''ODBC Link (Open Data Base Connectivity)''' - ODBC is a function library which provides a common API for ODBC compliant databases. CommitCRM provides an open database and allows other applications to access the database using ODBC for '''read-only''' purposes.

*'''Record''' - Each entity in the CommitCRM database (such as Ticket, Account, Asset, Item, Appointment, Task, etc.) is considered a "record".

*'''Database fields''' - Each record contains a list of fields, each of which holds the record's data.

*'''Transaction''' – All additions or updates to record in the database are done by using a transaction. Each transaction includes the operation you wish to perform, the data type you wish to add/update and the additional parameters (database fields and their values).

*'''Transaction Parameters''' - Each transaction contains the parameters for performing the transaction: record type, list of database fields and a list of the values to be updated in these fields.

*'''External Application''' - This refers to the external program which integrates with CommitCRM in order to update the database. This name should be passed when performing updates to the database, and it will be saved in the CommitCRM record to indicate who performed the changes.

*'''Record ID (REC ID)''' - Each record in CommitCRM has a '''unique Record ID''' which is created when adding the record to the database. Every ID is 20 characters and should be transferred with the API transaction when you need to update an existing record.

=Using Commit API=
Commit API allows you to add and update records in the CommitCRM database, such as
Accounts, Tickets, Assets, Items, Appointments, Tasks and more.

The updates are performed using transactions, where each transaction includes the
operation you wish to perform, the data type you wish to add/update, and any additional
parameters (i.e. record type, database fields and their values).

Every record added to the system is assigned a unique Record ID (REC ID) which is the
database identifier for this record.

The Commit API allows you to perform the following operations.

*'''Add new records''' - if no Record ID is passed in the transaction, the API assumes that this is a new record, adds it to the system and creates a new Record ID for it.

*'''Update existing records''' - if the record ID is passed in the transaction, and the record exists, the system will update the record with the information in the transaction.

In both cases, the system will try to set default values for fields which do not exist in the
incoming transaction. If it fails, the action will fail with an error.

Note that in order to '''read data''' from the CommitCRM database, you should use the ODBC
Link, which provides a read-only link for the CommitCRM database. See more details in
[[#Retrieving data using ODBC|Retrieving data using ODBC]].

==Workflow==
Following is a sample work-flow, which demonstrates the process of adding a new Account, and then adding a new Ticket to this Account, using the Commit API.

Note that the API can return two parameters to the External Application:
#The Commit REC ID - when adding new records to the database, this will contains the new record ID.
#The ExternalTransactionID (relevant for XML transaction only) - In case the external application passes a parameter to be returned with the response, the ExternalTransactionID will be returned as-is to in the response.

The External Application should keep the REC ID which is returned from the API response. This allows you to later update the existing records with new data or add records related to it (such as opening a Ticket under the Account).

[[File:flow.gif|center]]

==Updating existing records==
In order to update an already existing record in the database (e.g. add a Ticket to an
Account, update an Account's phone number, add a new Charge to an existing Ticket,
etc.), you should pass the record's unique identifier to the API so it will update the
existing record rather than create a new Account. The record's unique identifier is
referred to as the Record ID (REC ID).

The Record ID can be obtained in the following ways:
#'''API Response''' (as in the flow above) - You can extract the newly created Record ID from the Email Response when adding new records with the API. This requires the developer to process the API responses, and extract the returning REC ID for each newly added record.
#'''ODBC Link''' - Use the ODBC Link to find relevant records (Accounts, Tickets, etc.), and read all information from the database, including the unique Record ID.
#'''Manually''' - from the Account's Notes tab, at the bottom, right-click the REC ID field and copy it.

Once you have obtained the Record ID you can pass the Record ID as a parameter for the
API and update this record.

=Programming API=
The Programming API allows you access the CommitCRM database and perform transactions
from within a program (using various programming language). This means you can embed
code which accesses the CommitCRM database from within your own application, and add
your own functionality which updates the database.

The programming API executes database transactions. Each transaction uses API methods
provides by the API dll file which is located in the CommitCRM installation. Both the
Programming API and the API by Email use the same dll for performing the transactions.

Note that the API provides the tools needed for adding/updating information in the
database. In order to retrieve data, you should use the ODBC link which allows you to
connect to the database and retrieve data directly from the tables. You can read more
about it in the [[Commit_API_Developers_Guide#ODBC_Data_Retrieval|ODBC Data Retrieval]] section.

You can find more information and samples in the [[API Code Samples]] section.

=API by Email (XML transaction)=
The API by Email operates under the Commit Email Connector module, which
automatically processes incoming emails arriving at a defined public email address. The
Email may contain XML formatted messages which contain API transactions, and provides
a full API to CommitCRM.

The Email Connector pulls incoming emails from your POP3 mail server, and processes the
email. When an email containing XML formatted message is detected, the system analyzes
the XML content of the email and performs the transactions written in the XML. You may
set the Email Connector to send automatic replies in response to XML formatted email.

The API by Email executes database transactions. Each transaction uses API methods
provided by the API dll file which is located in the CommitCRM installation. Both the
Programming API and the API by Email use the same dll for performing the transactions.

Note that the API provides the tools for adding/updating information in the database. In
order to retrieve data, you should use the ODBC link which allows you to connect to the
database and retrieve data directly from the tables. You can read more about it in the
[[Commit_API_Developers_Guide#ODBC_Data_Retrieval|ODBC Data Retrieval]] section.

You can find more information and samples in [[API Code Samples#XML samples|XML samples]].

=ODBC Data Retrieval=
CommitCRM uses an open database and allows other applications to access it using ODBC
(Open Data Base Connectivity) for '''read-only''' purposes. While the API provides the means
for adding and updating information in the database, it is preferred to use ODBC to read
information from the database.

You can use ODBC Link to read data from the database and integrate it with an external
system (i.e. Crystal reports, or any other application). You may also use the ODBC Link in
order to read the Database Record ID and update existing records (see [[Commit_API_Developers_Guide#Updating_existing_records|Updating existing records]]).

'''Activation Notes:'''

*The ODBC drivers are well tested and work well, however, please note that the Commit Support team doesn't provide "pure ODBC" support.

*NEVER use ODBC to modify or delete data; use it for READ purposes only. Modifying data should be done using the Commit API.

*The ODBC Link can be used with your installed version of CommitCRM, and only requires installing an external driver. Before working with the API we recommend that you '''backup the database'''.

Below are the database table names and their meaning:
{| class="wikitable"
|-
! '''CommitCRM Record'''
! '''Database Table Name'''
|-
| Accounts
| Cards
|-
| Tickets
| Tickets
|-
| Charges
| Slips
|-
| Assets
| Assets
|-
| Appointments
| Events
|-
| Tasks
| Events
|-
| History Notes
| NoteBook
|-
| Opportunities
| Opps
|-
| Documents
| Docs
|-
| Knowledge Base
| KBArticles
|}

For the database fields list, please refer to [[Commit_API_Developers_Guide#API_Reference_Manual|API Reference Manual]] section.
You can find detailed instructions for using the ODBC Link in the [[Commit_API_Developers_Guide#Installing_ODBC_Driver|Installing ODBC Driver]] section.

==Installing ODBC Driver==
'''Product Overview''' 
The Advantage ODBC Driver is an ODBC version 3 driver based on the Advantage Client Engine that provides SQL access to the Advantage Database Server. The driver provides
full support for the "Minimum" ODBC SQL grammar specification, as well as many functions
included in the "Core" and "Extended" grammar specifications. When used with the
Advantage Database Server, ODBC users can have the
application stability, performance and reduced network traffic benefits of client/server
architecture.

'''Installation on Windows''' 
Like other ODBC drivers, the Advantage ODBC Driver is installed and managed using the
ODBC Administrator Utility. This utility works with the ODBC Driver Manager to configure
ODBC data sources. At runtime, the ODBC Driver Manager works with available drivers and
their configured data sources. If you have previously installed ODBC drivers, the ODBC Administrator may already be installed on your workstation. The icon for the Administrator is usually found in the Control Panel.

To install the Advantage ODBC Driver:
#[http://www.commitcrm.com/downloads/odbc9007.exe Click here] to download the Advantage ODBC setup program.
#Run the Setup program.
#Proceed through the setup windows to complete installation.

'''Data Source Setup for Windows''' 
Once the Advantage ODBC Driver is installed, a data source needs to be configured to use
the Advantage ODBC Driver. The data source is an entry in the Windows Registry. When a
data source is defined for the Advantage Driver, all information specific to the Advantage
Driver and database files is stored under the Data Source entry in the Windows 95/98/ME/
NT/2000/2003/XP Registry. 
The database files and indexes must be stored on your file server, and the Advantage
Database Server must be loaded in order to access the files.

The Data Source settings may be modified at any time. Using the ODBC Administrator, you
may modify the Data Source and Option settings.
For specific information about the screen fields see the Data Source Setup Screen.

'''To Setup the Data Source:'''
#From the ODBC Administrator, click Add.
#Highlight the Advantage SQL ODBC line, and click OK.
#Type a unique data source name. For example, type AdvData. This name is used by applications to reference the data source.
#Specify the database or data dictionary path. Type a valid path name to a mapped drive on the server where the Advantage Database Server is installed or the path and file name of your Advantage Data Dictionary. Click Browse to select a database path or check the Data Dictionary check box and then browse to select a data dictionary file. Note Multiple Advantage data sources may need to be defined for your environment. If different settings are needed for ODBC connections in one application, separate data sources may be required.
#Review the options and change them to your desired setup.
#Once the Options are reviewed and/or altered, click OK to exit and save the settings. The new data source is displayed.
#Click Close to exit the ODBC Administrator.

'''ODBC Data Source Entries for Windows''' 
In Microsoft Windows, the entries are registry settings found on HKEY_CURRENT_USER\Software\ODBC\ODBC.INI\ (your unique data source name) or HKEY_LOCAL_MACHINE\Software\ODBC\ODBC.INI (your unique data source name). Unless specified otherwise, all registry entries can be setup by the Advantage ODBC Driver setup utility. See Data Source Setup for Windows and Data Source Setup Screen for more information. ODBC Data Source Keys.

'''ODBC Data Source Keys''' 
The following ODBC registry is '''required''' for the driver to load:
{| class="wikitable"
|-
! '''Registry Entry'''
! '''Comments'''
|-
| DataDirectory=data path
| 'data path' should be a valid path name for files locations (e.g., x:\data). This path is used to automatically select all tables in the specified directory.
|-
| DefaultType=Advantage
| Sets a certain type of database files to use Advantageproprietary ADT/ADI/ADM files.
|-
| ServerTypes=3
| Allows the Driver to use the remote or local server
|}

The following ODBC registry keys are '''optional''':

{| class="wikitable"
|-
! '''Registry Entry'''
! '''Comments'''
|-
| AdvantageLocking=ON \ OFF
| The default is ON to use the Advantage proprietary locking.
|-
| CharSet=OEM \ ANSI
| The default character collation setting is ANSI. If OEM is specified, Language must be indicated as well.
|-
| Language=USA
| Used if CharSet=OEM.
|-
| Description=String
| This is provided for easier administration.
|-
| Locking=RECORD \ FILE
| Indicates whether updates lock the entire file or the individual records that are updated. The default is RECORD.
|-
| MaxTableCloseCache=n
| N is the number of tables to hold in cache when cursors are opened and closed. The default is 25.
|-
| MemoBlockSize=n
| N is the size of the Advantage memo blocks in tables that are created by the ODBC driver. The default value is 8 for Advantage proprietary table (ADT/ADM).
|-
| Rows=TRUE \ FALSE
| Select whether deleted rows are displayed. If True, deleted rows are displayed. The default is False.
|-
| TrimTrailingSpaces=TRUE \ FALSE
| The default is False. If True is specified, trailing spaces in character fields will be removed prior to returning the values to the application.
|}

==Troubleshooting ODBC in 64 Bit Operating Systems==
The Commit ODBC drivers are mainly distributed for 32-bit operating systems; however, the same drivers are supported on the 64-bit operating systems (I.e. Windows 7 x64), and can be used to retrieve data from the CommitCRM database.

 
===Configuring Data Source in 64-Bit Systems===
When installing the ODBC drivers on 64-bit operating systems, the ODBC drivers may not be displayed in the default ODBC manager in windows control panel. In order to view the 32-bit ODBC manager in a 64-bit operating system, you’ll need to browse to '''%windir%\SysWOW64\odbcad32.exe''' and run the 32 bit ODBC Administrator manually. Once the data source has been configured there, you should be able to select the data source in your 3rd party ODBC programs.

 
=Samples=
The Commit API allows you to add/update the following entities:
*Accounts
*Assets
*Tickets
*Charges
*Appointments
*Tasks
*History Notes
*Opportunities
*Documents
*Knowledge Base Articles

Each API method requires a list of parameters which contain the field names and their values. The field names are the Database field names. You can see each field's name within the application (so you can verify which field you are about to update), by right-clicking the field and selecting Field Settings > Advanced Tab > view the Tech. Rec ID field.

You can view the complete list of database fields in the [[Commit_API_Developers_Guide#API_Reference_Manual|API Reference Manual]] above.

Following are samples for using the API by Email and the Programming API. The samples are basic and provide an easy starting point.

See [[API Code Samples]].

=API Reference Manual=

The API allows you to add/update the following entities:
*Accounts
*Assets
*Tickets
*Charges (and Contract-price Charges)
*Appointments
*Tasks
*History Notes
*Opportunities
*Documents
*Knowledge Base Articles

You can find a detailed listing of the database fields in the [[API Reference Manual]].

=See Also=
*[[API Code Samples]]
*[[API Reference Manual]]
*[[Email Connector|Commit Email Connector]]
*[[API by Email and MSP Integration]]
*[[MSP Integration Setup]]
*[http://www.commitcrm.com/sql_database_server.htm Commit SQL Database (CSD)]
*[[Commit SQL Database Installation Guide | Commit SQL Database (CSD) Installation Guide]]

[[Category:User Manuals]]
[[Category:Integration]]

SQL Database Troubleshooting

2010-04-07T19:24:51Z

Reno: /* ADS.ini – Server Locator (Supplemental) */

__TOC__

 
==Problem Description==
When setting up the Commit SQL Database (CSD), the client PCs running the CommitCRM client application cannot connect to the Commit SQL Database, and an error is displayed saying:

Procedure halted due to data server error. Verify server is operating and this computer has access to the server folder. (C:\Commit\DB)

 
[[File:Error.jpg]]

 

==Explanation==
This problem occurs when the client PCs try to connect to the Commit SQL Database, which is installed on your server, and it doesn’t “answer” to their connection requests.
By default, CommitCRM clients send a UDP broadcast message on the network, checking where the Commit SQL Database server is found; if found the server answers with the relevant information for the client to connect to it (IP, Port, etc.). This handshake process may require allowing UDP broadcasts inside you LAN. Usually this does not require any special setup; however, with some advanced network security settings it may be required.
It is also required that the Commit SQL Database, which runs on your server as a Windows service called Advantage Database Server, will be up and running and be allowed to communicate with your LAN.

 

==Troubleshooting Steps==
In order to assure the Commit SQL Database can communicate with the CommitCRM clients, we ask that you cover the following steps.

*'''Please remember to test the Commit SQL Database communications again after applying each step, and if the issue persists, then the next step should be applied.'''

===Advantage Server===
*Verfiy the Advantage Database Server service is started on your server. For installation instructions click [[Commit_SQL_Database_Installation_Guide|here]] or [[Commit_SQL_Database_for_Trial_Users|here]] if your are using a trial copy of CSD.

*'''Please restart all Commit services, and retest communications by loading a CommitCRM Client application from another computer.'''

===DEP – Data Execution Prevention===
*Please ensure that if using DEP on the server, where Commit SQL Database (aka, Advantage Database Server) is installed, it should be configured to allow data execution for '''ADS.exe''', by default located in the following folder '''C:\Program Files\Extended Systems\Advantage 9007\Server'''. This file is the Commit SQL Database / Advantage Database Server Windows service executable file and therefore should be allowed, or else DEP may isolate the CSD software from communicating with the CommitCRM client applications.

*'''Please restart the Advantage service & all Commit services, and retest communications by loading a CommitCRM Client application from another computer.'''

 

===Firewall - Windows or any other installed Firewall===
*Make sure that your software firewall allows the Advantage port through the firewall (Advantage prot information can be adjusted from '''Start Menu > Programs > Advantage Database Server 9.0 > Advantage Configuration Utility > Configuration Utility tab > Communications tab'''). Also, make sure that no special UDP restrictions are activated on the CommitCRM server.
*If advanced firewall restrictions are configured, please verify that an exception has been placed in the firewall, so that the software may communicate with the network, as well as allowing UDP traffic through the firewall.

*'''Please restart the Advantage service & all Commit services, and retest communications by loading a CommitCRM Client application from another computer.'''

 

===ADS.ini – Server Locator===
*The CommitCRM client's way of finding the Commit SQL Database Server fails. In order for the client to detect where the server is running it broadcasts a UDP message and asks for the server to answer. When the server answers the client knows the server IP and can communicate with it.
*On your server, you can run the Advantage Configuration Utility ('''Start Menu > Programs > Advantage Database Server 9.0 > Advantage Configuration Utility > Configuration Utility tab > Communications tab'''). Using it you can find the Port number which is used for communicating with the clients. When adjusting the CSD ports, you can use any port you like, as long as the port is not being used by any other software.

 
[[File:Communicationstab.jpg]]
 
 
As explained in the previous steps, you should make sure that the Windows firewall on each client on your LAN allows communication with the server for this port. Verifying this will allow communication between the CommitCRM client and Commit SQL Database on the server.
 
 
However, in some cases this is not enough. As explained above, a discovery process takes place when the client loads, trying to find the server... It is possible that your Windows firewall blocks this discovery process even if the port is allowed.
 
 
Therefore, in case you enabled the port on each client (using the firewall settings window) and CommitCRM client still doesn't load, you should continue with the following ('''do not continue with this before testing whether allowing the port has solved the issue'''):

Under the '''<server>\Commit\LastVer'''  folder, create a text file called '''ADS.INI'''
Open this file in Notepad and add the following settings:

'''[MYSERVER] LAN_IP=192.168.0.1 LAN_PORT=2001 ''' 
''IMPORTANT NOTES'':
*Replace '''MYSERVER''' with the name of '''YOUR server'''
*Replace the '''192.168.0.1''' IP address with the '''LOCAL IP address of your server'''.
*Replace the port number '''2001 '''to the one used for Commit SQL Database in your setup ('''this can be viewed by running Advantage Configuration Utility on your server, look for the port in use for your LAN''').

After adding the relevant settings, save the file and then try to run CommitCRM client.
This file tells the CommitCRM client what the server IP is and what port to use and therefore no discovery process is required, avoiding the broadcast stage.

Please remember that in case you ever change the IP of your server on your LAN, you should make sure to update this file again to reflect the change. This is why we usually recommend on allowing the broadcast rather than using this hard-coded method of communication; however, in some configurations it doesn’t work and using an ADS.ini file is mandatory.

*'''Please restart the Advantage service & all Commit services, and retest communications by loading a CommitCRM Client application from another computer.'''
 
 

===ADS.ini – Server Locator (Supplemental)===
*If the Ads.ini file does not correct the issue, then we suggest that '''changing the Server hostname reference''' in ADS.ini to the '''server IP address [192.168.x.x]''' will correct this behavior. (Remember to restart Advantage Service each time ADS.ini is adjusted)
For example:
'''[192.168.0.1] LAN_IP=192.168.0.1 LAN_PORT=2001 '''
''IMPORTANT NOTE:''
*Please replace the ServerName (between the brackets) with '''the servers IP adress''', as displayed in the example above.

*'''Please restart the Advantage service & all Commit services, and retest communications by loading a CommitCRM Client application from another computer.'''

 
====Important Note For ODBC Users====
Some newer Windows systems may still present an error message regarding failure of the Discovery process (Advantage Error 6316) when setting up an ODBC connection, even after the ADS.ini file has resolved the issues with CommitCRM clients being able to discover the Advantage server. The following solution should resolve this issue as long as the following bullets are true:
*You use the Commit SQL Database (Advantage) and ODBC.
*The ADS.ini file succeeded in logging in the CommitCRM Software Applications (Clients).
*You receive a message regarding Database Discovery Failure.

If all of the above prerequisites exist, you should copy the ADS.ini file from the CommitCRM server into the following folder on the affected workstation:
* '''%Windir%\'''
* '''%Windir%\system32'''

'''Note:''' Paste the paths into a Run dialog box, or into any Windows Explorer path.

 

==Recurring issues after Rebooting the CommitCRM Server Machine==
The CommitCRM database chooses its database mode upon the first concurrent connection to the system. If a client application, or Commit Addon Service (Such as '''CommmitWebInterface''' or '''CommitServer''')service is already loaded and connected to the server before the Advantage Database Server service finishes loading, then all subsequent connections will be rejected since the prior connection to the database would not allow the Advantage Database Server service full control over the database.

Typical characteristics of this type of problem are repeated manual attention needed to properly connect Advantage Database Server to CommitCRM after rebooting, and restarting the Advantage Database Server service.
To verify this is the issue, please follow these steps:
#Stop any '''Commit Services''' installed in the CommitCRM server.
#Verify no other computers are running CommitCRM.
#Restart the '''Advantage Database Server''' Service.
#Once the '''Advantage Database Server''' service has started, Try Logging in with one client on the '''server machine'''.
#Check the CommitCRM window title to see if '''SQL''' is printed next to your username.
#If successful, Start '''Commit Services'''.

If this process was successful, this is because the '''Commit Services loaded before Advantage Database Server did''', locking Advantage Database Server out of the CommitCRM database. To permanently resolve this behavior, manual rules will''' need to be created''' in order to ensure that The Commit Services '''do not try to load without Advantage Database Server being started'''.

 
===Adding Service Dependency Rules===
Now that CommitCRM depends on the Advantage Database Server Database service, the Commit Services (CommitWebInterface & CommitServer) also need the Advantage Database Server server to to be up before they try to load.
To set these services to be dependent on the Advantage Database Server Service, follow these steps:
# Backup your current registry settings.
# Run '''regedit''' to open your registry.
# Navigate to '''HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services''' and locate the '''CommitWebInterface/CommitServer''' services that you need to set a dependency for.
# Open the '''DependOnService''' key on the right side. If the selected service does not have a '''DependOnService''' key, then create one by right-clicking and selecting '''New > Multi-String Value'''.
# In the '''value''' field, enter '''Advantage Database Server'''.
# Click OK, close your registry and restart your machine.

 

==See Also==
*[[Commit_SQL_Database_Installation_Guide|Commit SQL Database Installation Guide]]
*[[Commit_SQL_Database_for_Trial_Users|Commit SQL Database for Trial Users]]
[[Category:Troubleshooting]]

SQL Database Installation Guide

2010-04-02T21:25:26Z

Reno: /* See Also */

{{setup}}
==Introduction==
The following document contains instructions for installing the Commit SQL Database add-on.

==Installation Instructions==

Please follow the instructions bellow to install Commit SQL Database.

Run the installation file on your server using an Administrator user.
The following window will open:

Click Next.

[[File:1.jpg|center]]

Use the default installation folder and just click Next.

[[File:2.jpg|center]]

Type '''your serial number (not the one displayed bellow)''', check 'I have a product validation
code', and enter '''your validation code'''. You should leave the ‘Replication Code’ field empty.

Click Next.

[[File:7r.jpg|center]]

In the Registered Owner field, type 'Commit' or your business name.
And select ‘Automatic Startup’.

[[File:4t.jpg|center]]

After the registration has completed successfully the following window is displayed:
If the Advantage Configuration Utility will appear, just exit from it.

[[File:9.jpg|center]]

Verifying the installation:

The Commit SQL Database runs on the server as a service called 'Advantage Database Server'.

If you have any program control software installed on your server remember to allow this service
to act as a server.

In order to start / stop the database server simply start and stop the service (called 'Advantage
Database Server') from the Service Manager window (control panel -> administrative tools ->
services). Please make sure no one is using Commit when you stop the service.

[[File:10.jpg|center]]

Done! Commit SQL Database is installed.

==See Also==
*[[Commit SQL Database for Trial Users|Commit SQL Database Installation for Trial Users]]
*[[Commit_SQL_Database_Troubleshooting|Commit SQL Troubleshooting]]
*[[Commit API Developers Guide]]
[[Category:Setup]]
[[Category:Installation]]

SQL Database for Trial Users

2010-04-02T21:24:55Z

Reno: /* See Also */

{{setup}}
==Introduction==
The following documents explains how to install a trial Commit SQL Database. Using this requires contacting the Commit Support team in order to receive trial licenses for the Commit SQL Database.

__TOC__

==Installation Instructions==

Please follow the instructions bellow to install the Commit SQL Database for Trial Users.

Log in as an Administrator, and run the installation file on your server.
The following window is displayed:

Click '''Next'''.

[[File:1.jpg|center]]

Use the default installation folder and just click '''Next'''.

[[File:2.jpg|center]]

Type '''your serial number (not the one displayed bellow)''', check 'I have an evaluation Authorization code', and enter '''your authorization code'''.

Click '''Next'''.

[[File:3t.jpg|center]]

In the '''Registered Owner''' field, enter or the name of your business. Select '''Automatic Startup''', and click '''Next'''.

[[File:4t.jpg|center]]

Once the registration is complete, the following window is displayed:

[[File:9.jpg|center]]

Click '''Exit'''.

====Verifying the installation:====
The Commit SQL Database runs on the server as a service called the Advantage Database Server.

If you have any program control software installed on your server, remember to allow the Advantage Database Server to act as a server.

In order to start/stop the database server, start and stop the service (named Advantage Database Server) from the Service Manager window (Control Panel > Administrative Tools > Services). Make sure that no one is using Commit when you stop the service.

[[File:10.jpg|center]]

Congratulations! You have installed the Commit SQL Database.

==See Also==
*[[Commit SQL Database Installation Guide|Commit SQL Database Installation for Registered Users]]
*[[Commit_SQL_Database_Troubleshooting|Commit SQL Troubleshooting]]

[[Category:Setup]]
[[Category:Installation]]
__NOTOC__

SQL Database for Trial Users

2010-04-02T21:24:22Z

Reno: /* See Also */

{{setup}}
==Introduction==
The following documents explains how to install a trial Commit SQL Database. Using this requires contacting the Commit Support team in order to receive trial licenses for the Commit SQL Database.

__TOC__

==Installation Instructions==

Please follow the instructions bellow to install the Commit SQL Database for Trial Users.

Log in as an Administrator, and run the installation file on your server.
The following window is displayed:

Click '''Next'''.

[[File:1.jpg|center]]

Use the default installation folder and just click '''Next'''.

[[File:2.jpg|center]]

Type '''your serial number (not the one displayed bellow)''', check 'I have an evaluation Authorization code', and enter '''your authorization code'''.

Click '''Next'''.

[[File:3t.jpg|center]]

In the '''Registered Owner''' field, enter or the name of your business. Select '''Automatic Startup''', and click '''Next'''.

[[File:4t.jpg|center]]

Once the registration is complete, the following window is displayed:

[[File:9.jpg|center]]

Click '''Exit'''.

====Verifying the installation:====
The Commit SQL Database runs on the server as a service called the Advantage Database Server.

If you have any program control software installed on your server, remember to allow the Advantage Database Server to act as a server.

In order to start/stop the database server, start and stop the service (named Advantage Database Server) from the Service Manager window (Control Panel > Administrative Tools > Services). Make sure that no one is using Commit when you stop the service.

[[File:10.jpg|center]]

Congratulations! You have installed the Commit SQL Database.

==See Also==
*[[Commit SQL Database Installation Guide|Commit SQL Database Installation for Registered Users]]
[[Commit_SQL_Database_Troubleshooting|Commit SQL Troubleshooting]]

[[Category:Setup]]
[[Category:Installation]]
__NOTOC__

KB: Database Errors, Indexing Errors

2010-04-01T19:55:22Z

Reno: /* Description */

=Description=
Sometimes the database indexes that govern search results from the database can be corrupted for several reasons, causing inconsistent behavior when searching or loading specifically affected parts of the database. This behavior can be corrected by rebuilding your database indexes so that the data can be reassessed and properly tagged by the index files. This process is considered safe to run in order to correct suspected database indexing errors. It may also be a good practise to run it once every several months in order to make sure that the indexes are in order and up to date. In some cases, reindexes your database may also increase the overall system performance.

 

=Resolution=
'''Please run the CommitCRM Backup Utility prior to Rebuilding the Database Indexes'''

To run the rebuild indexes, please follow these instructions: (Make sure you're using CommitCRM 5.0 and above)

:* 1. Close CommitCRM client on all PCs

:* 2. Stop CommitWebInterface and CommitServer services (if installed and used). Leave the Advantage Service running if you are using the CSD.

:* 3. Backup the <server>\Commit\Db and <server>\Commit\DbSys folders (use a standard zip/archive utility for this (such as Winzip), and/or, also copy the folder to a backup folder.

:* 4. [http://www.commitcrm.com/downloads/commit-rebuild-indexes-50.exe Click here] to download a Rebuild Indexes program => '''Save it in folder <server>\Commit\Utils'''

:* 5. Run the downloaded program and have it rebuild the indexes

----
Check to see if the problem has been resolved.

If the issue persists, we will need some more information in order for us to investigate:

----
:* Send us the log files via '''Help > Technical Support'''.

We'll analyze the logs, get you the support needed to fix this issue.

[[Category:KB|Database]]

KB: Database Errors, Indexing Errors

2010-04-01T19:52:31Z

Reno: /* Description */

=Description=
Sometimes the database indexes that govern search results from the database can be corrupted for several reasons, causing inconsistent behavior when searching or loading specifically affected parts of the database. This behavior can be corrected by rebuilding your database indexes so that the data can be reassessed and properly tagged by the index files. This process is considered safe to run in order to correct suspected database indexing errors. It may also be a good practise to run it once every several months in order to make sure that the indexes are in order and up to date. In some cases, reindexes your database may also increase the overall system performance. It is important that you backup your system before running reindexing the database.

 

=Resolution=
'''Please run the CommitCRM Backup Utility prior to Rebuilding the Database Indexes'''

To run the rebuild indexes, please follow these instructions: (Make sure you're using CommitCRM 5.0 and above)

:* 1. Close CommitCRM client on all PCs

:* 2. Stop CommitWebInterface and CommitServer services (if installed and used). Leave the Advantage Service running if you are using the CSD.

:* 3. Backup the <server>\Commit\Db and <server>\Commit\DbSys folders (use a standard zip/archive utility for this (such as Winzip), and/or, also copy the folder to a backup folder.

:* 4. [http://www.commitcrm.com/downloads/commit-rebuild-indexes-50.exe Click here] to download a Rebuild Indexes program => '''Save it in folder <server>\Commit\Utils'''

:* 5. Run the downloaded program and have it rebuild the indexes

----
Check to see if the problem has been resolved.

If the issue persists, we will need some more information in order for us to investigate:

----
:* Send us the log files via '''Help > Technical Support'''.

We'll analyze the logs, get you the support needed to fix this issue.

[[Category:KB|Database]]

KB: Database Errors, Indexing Errors

2010-04-01T19:48:09Z

Reno: /* Description */

=Description=
Sometimes the index files that govern search results from the database can be corrupted for several reasons, causing inconsistent inconsistent behavior when searching or loading specifically affected parts of the database. This behavior can be corrected by rebuilding your database indexes so that the data can be reassessed and properly tagged by the index files. This process is considered safe to run in order to correct suspected database indexing errors; however, it is also considered good practice to periodically run this process in order to make sure that the indexes are in order and up to date.

 

=Resolution=
'''Please run the CommitCRM Backup Utility prior to Rebuilding the Database Indexes'''

To run the rebuild indexes, please follow these instructions: (Make sure you're using CommitCRM 5.0 and above)

:* 1. Close CommitCRM client on all PCs

:* 2. Stop CommitWebInterface and CommitServer services (if installed and used). Leave the Advantage Service running if you are using the CSD.

:* 3. Backup the <server>\Commit\Db and <server>\Commit\DbSys folders (use a standard zip/archive utility for this (such as Winzip), and/or, also copy the folder to a backup folder.

:* 4. [http://www.commitcrm.com/downloads/commit-rebuild-indexes-50.exe Click here] to download a Rebuild Indexes program => '''Save it in folder <server>\Commit\Utils'''

:* 5. Run the downloaded program and have it rebuild the indexes

----
Check to see if the problem has been resolved.

If the issue persists, we will need some more information in order for us to investigate:

----
:* Send us the log files via '''Help > Technical Support'''.

We'll analyze the logs, get you the support needed to fix this issue.

[[Category:KB|Database]]

KB: Database Errors, Indexing Errors

2010-04-01T19:47:29Z

Reno: /* Resolution */

=Description=
Sometimes the index files that govern search results from the database can be corrupted for several reasons, causing inconsistent results from searching or loading specifically affected parts of the database. This behavior can be corrected by rebuilding your database indexes so that the data can be reassessed and properly tagged by the index files. This process is considered safe to run in order to correct suspected database indexing errors; however, it is also considered good practice to periodically run this process in order to make sure that the indexes are in order and up to date.

 

=Resolution=
'''Please run the CommitCRM Backup Utility prior to Rebuilding the Database Indexes'''

To run the rebuild indexes, please follow these instructions: (Make sure you're using CommitCRM 5.0 and above)

:* 1. Close CommitCRM client on all PCs

:* 2. Stop CommitWebInterface and CommitServer services (if installed and used). Leave the Advantage Service running if you are using the CSD.

:* 3. Backup the <server>\Commit\Db and <server>\Commit\DbSys folders (use a standard zip/archive utility for this (such as Winzip), and/or, also copy the folder to a backup folder.

:* 4. [http://www.commitcrm.com/downloads/commit-rebuild-indexes-50.exe Click here] to download a Rebuild Indexes program => '''Save it in folder <server>\Commit\Utils'''

:* 5. Run the downloaded program and have it rebuild the indexes

----
Check to see if the problem has been resolved.

If the issue persists, we will need some more information in order for us to investigate:

----
:* Send us the log files via '''Help > Technical Support'''.

We'll analyze the logs, get you the support needed to fix this issue.

[[Category:KB|Database]]

KB: Database Errors, Indexing Errors

2010-04-01T19:46:24Z

Reno: /* Description */

=Description=
Sometimes the index files that govern search results from the database can be corrupted for several reasons, causing inconsistent results from searching or loading specifically affected parts of the database. This behavior can be corrected by rebuilding your database indexes so that the data can be reassessed and properly tagged by the index files. This process is considered safe to run in order to correct suspected database indexing errors; however, it is also considered good practice to periodically run this process in order to make sure that the indexes are in order and up to date.

 

=Resolution=
We fix this issue by '''Rebuilding the Database Indexes'''

To run the rebuild indexes, please follow these instructions: (Make sure you're using CommitCRM 5.0 and above)

:* 1. Close CommitCRM client on all PCs

:* 2. Stop CommitWebInterface and CommitServer services (if installed and used). Leave the Advantage Service running if you are using the CSD.

:* 3. Backup the <server>\Commit\Db and <server>\Commit\DbSys folders (use a standard zip/archive utility for this (such as Winzip), and/or, also copy the folder to a backup folder.

:* 4. [http://www.commitcrm.com/downloads/commit-rebuild-indexes-50.exe Click here] to download a Rebuild Indexes program => '''Save it in folder <server>\Commit\Utils'''

:* 5. Run the downloaded program and have it rebuild the indexes

----
Check to see if the problem has been resolved.

If the issue persists, we will need some more information in order for us to investigate:

----
:* Send us the log files via '''Help > Technical Support'''.

We'll analyze the logs, get you the support needed to fix this issue.

[[Category:KB|Database]]

Videos

2010-03-24T21:19:17Z

Reno: /* Installation Guides */

For better playback, allow the videos to download before playing.
====Getting Started====
*[http://www.commitcrm.com/videos/commit_crm_getting_started_tutorial_video.htm Getting Started Tutorial] - '''Recommended!''' (15 min.)

====Installation Guides====
*[http://www.commitcrm.com/videos/web_interface_installation_video.htm Web Interface Installation] (6 min.)
*[http://www.commitcrm.com/videos/email_connector_setup_video.htm Email Connector Installation] (12 min.)
*[http://www.commitcrm.com/videos/commit_alert_server_setup_video.htm Alerts Server Installation] (8 min.)
*[http://www.commitcrm.com/videos/commitcrm_upgrades_video.htm Upgrading CommitCRM] (3 min.)

====Contracts & Billing====
*[http://www.commitcrm.com/videos/commit_contracts_introduction_video.htm Contracts Introduction] (4 min.)
*[http://www.commitcrm.com/videos/commit_contracts_global_tutorial_video.htm Global Contracts] (6 min.)
*[http://www.commitcrm.com/videos/commit_contracts_block_of_time_tutorial_video.htm Block Of Time Contracts] (7 min.)
*[http://www.commitcrm.com/videos/commit_contracts_block_of_money_tutorial_video.htm Block Of Money Contracts] (6 min.)
*[http://www.commitcrm.com/videos/commit_contracts_block_of_tickets_tutorial_video.htm Block Of Tickets Contracts] (5 min.)
*[http://www.commitcrm.com/videos/commit_contracts_management_tutorial_video.htm Contract Status and Billing] (7 min.)
*[http://www.commitcrm.com/videos/commit_contracts_contract_price_charges_video.htm Contract-Price Charges] (7 min.)
*[http://www.commitcrm.com/videos/commit_contracts_batch_copy_wizard_video.htm Renewing Recurring Contracts] (4 min.)

====Additional Tutorials====
*[http://www.commitcrm.com/videos/employee_web_interface_tutorial_video.htm Web Interface For Employees] (6 min.)
*[http://www.commitcrm.com/videos/commit_activity_templates_video.htm Managing Activity Templates] (7 min.)
*[http://www.commitcrm.com/videos/commit_report_designer_tutorial_video.htm Report Designer Tutorial] (7 min.)

 
=====Other Videos=====

'''Manage Accounts:''' Your IT service business Customers, Contacts and Leads
*[http://www.commitcrm.com/videos/new_account.htm See how to add a new Account in Commit™] (33 sec.)

'''Manage IT Service Contracts:''' Block of Time, Block of Money, Block of Tickets, Date Range etc.
*[http://www.commitcrm.com/videos/new_contract.htm See how to create a new Contract for an Account] (1 min, 16 sec.)

'''Manage Tickets''' and increase control over all the open issues, incidents and problems.
*[http://www.commitcrm.com/videos/new_ticket.htm See how to create a new Ticket in Commit™] (45 sec.)
*[http://www.commitcrm.com/videos/charging_ticket.htm See how to add Charges to an open Ticket in Commit™] (42 sec.)

'''Increase Productivity by Dispatching''' the right technician to the right call and by measuring the technician's productivity.

[[Category:Getting Started]]
*[http://www.commitcrm.com/videos/dispatching_ticket.htm See how to dispatch an open service ticket to a technician] (44 sec.)

'''Organize Your Price List''' for products and services.
*[http://www.commitcrm.com/videos/new_labor_item.htm See how to create a new item in Commit™] (41 sec.)

'''Increase Revenues by Easily Entering Charges''' for labor services, expenses, products and parts.
*[http://www.commitcrm.com/videos/new_part_charge.htm See how to create a new Charge in Commit™] (25 sec.)
*[http://www.commitcrm.com/videos/charging_ticket.htm See how to add charges to a service Ticket] (42 sec.)

'''Eliminate paperwork! Easily Manage All Documents''' including MS-Word®, MS-Excel®, presentations, emails, scanned documents etc.
*[http://www.commitcrm.com/videos/importing%20_documents.htm See how to import existing documents folders and link them to your accounts] (45 sec.)

__NOTOC__

[[Category:Setup]]

Videos

2010-03-24T21:12:44Z

Reno: /* Installation Guides */

For better playback, allow the videos to download before playing.
====Getting Started====
*[http://www.commitcrm.com/videos/commit_crm_getting_started_tutorial_video.htm Getting Started Tutorial] - '''Recommended!''' (15 min.)

====Installation Guides====
*[http://www.commitcrm.com/videos/web_interface_installation_video.htm Web Interface Installation] (6 min.)
*[http://www.commitcrm.com/videos/email_connector_setup_video.htm Email Connector Installation] (12 min.)
*[http://www.commitcrm.com/videos/commit_alert_server_setup_video.htm Alerts Server Installation] (8 min.)
*[http://www.commitcrm.com/videos/commitcrm_upgrades_video.htm CommitCRM Upgrading CommitCRM to a Newer Release] (3 min.)

====Contracts & Billing====
*[http://www.commitcrm.com/videos/commit_contracts_introduction_video.htm Contracts Introduction] (4 min.)
*[http://www.commitcrm.com/videos/commit_contracts_global_tutorial_video.htm Global Contracts] (6 min.)
*[http://www.commitcrm.com/videos/commit_contracts_block_of_time_tutorial_video.htm Block Of Time Contracts] (7 min.)
*[http://www.commitcrm.com/videos/commit_contracts_block_of_money_tutorial_video.htm Block Of Money Contracts] (6 min.)
*[http://www.commitcrm.com/videos/commit_contracts_block_of_tickets_tutorial_video.htm Block Of Tickets Contracts] (5 min.)
*[http://www.commitcrm.com/videos/commit_contracts_management_tutorial_video.htm Contract Status and Billing] (7 min.)
*[http://www.commitcrm.com/videos/commit_contracts_contract_price_charges_video.htm Contract-Price Charges] (7 min.)
*[http://www.commitcrm.com/videos/commit_contracts_batch_copy_wizard_video.htm Renewing Recurring Contracts] (4 min.)

====Additional Tutorials====
*[http://www.commitcrm.com/videos/employee_web_interface_tutorial_video.htm Web Interface For Employees] (6 min.)
*[http://www.commitcrm.com/videos/commit_activity_templates_video.htm Managing Activity Templates] (7 min.)
*[http://www.commitcrm.com/videos/commit_report_designer_tutorial_video.htm Report Designer Tutorial] (7 min.)

 
=====Other Videos=====

'''Manage Accounts:''' Your IT service business Customers, Contacts and Leads
*[http://www.commitcrm.com/videos/new_account.htm See how to add a new Account in Commit™] (33 sec.)

'''Manage IT Service Contracts:''' Block of Time, Block of Money, Block of Tickets, Date Range etc.
*[http://www.commitcrm.com/videos/new_contract.htm See how to create a new Contract for an Account] (1 min, 16 sec.)

'''Manage Tickets''' and increase control over all the open issues, incidents and problems.
*[http://www.commitcrm.com/videos/new_ticket.htm See how to create a new Ticket in Commit™] (45 sec.)
*[http://www.commitcrm.com/videos/charging_ticket.htm See how to add Charges to an open Ticket in Commit™] (42 sec.)

'''Increase Productivity by Dispatching''' the right technician to the right call and by measuring the technician's productivity.

[[Category:Getting Started]]
*[http://www.commitcrm.com/videos/dispatching_ticket.htm See how to dispatch an open service ticket to a technician] (44 sec.)

'''Organize Your Price List''' for products and services.
*[http://www.commitcrm.com/videos/new_labor_item.htm See how to create a new item in Commit™] (41 sec.)

'''Increase Revenues by Easily Entering Charges''' for labor services, expenses, products and parts.
*[http://www.commitcrm.com/videos/new_part_charge.htm See how to create a new Charge in Commit™] (25 sec.)
*[http://www.commitcrm.com/videos/charging_ticket.htm See how to add charges to a service Ticket] (42 sec.)

'''Eliminate paperwork! Easily Manage All Documents''' including MS-Word®, MS-Excel®, presentations, emails, scanned documents etc.
*[http://www.commitcrm.com/videos/importing%20_documents.htm See how to import existing documents folders and link them to your accounts] (45 sec.)

__NOTOC__

[[Category:Setup]]

Videos

2010-03-24T20:42:03Z

Reno: /* Installation Guides */

For better playback, allow the videos to download before playing.
====Getting Started====
*[http://www.commitcrm.com/videos/commit_crm_getting_started_tutorial_video.htm Getting Started Tutorial] - '''Recommended!''' (15 min.)

====Installation Guides====
*[http://www.commitcrm.com/videos/web_interface_installation_video.htm Web Interface Installation] (6 min.)
*[http://www.commitcrm.com/videos/email_connector_setup_video.htm Email Connector Installation] (12 min.)
*[http://www.commitcrm.com/videos/commit_alert_server_setup_video.htm Alerts Server Installation] (8 min.)
*[http://www.commitcrm.com/videos/commitcrm_upgrades_video.htm CommitCRM Upgrades Demonstration Video] (4 min.)

====Contracts & Billing====
*[http://www.commitcrm.com/videos/commit_contracts_introduction_video.htm Contracts Introduction] (4 min.)
*[http://www.commitcrm.com/videos/commit_contracts_global_tutorial_video.htm Global Contracts] (6 min.)
*[http://www.commitcrm.com/videos/commit_contracts_block_of_time_tutorial_video.htm Block Of Time Contracts] (7 min.)
*[http://www.commitcrm.com/videos/commit_contracts_block_of_money_tutorial_video.htm Block Of Money Contracts] (6 min.)
*[http://www.commitcrm.com/videos/commit_contracts_block_of_tickets_tutorial_video.htm Block Of Tickets Contracts] (5 min.)
*[http://www.commitcrm.com/videos/commit_contracts_management_tutorial_video.htm Contract Status and Billing] (7 min.)
*[http://www.commitcrm.com/videos/commit_contracts_contract_price_charges_video.htm Contract-Price Charges] (7 min.)
*[http://www.commitcrm.com/videos/commit_contracts_batch_copy_wizard_video.htm Renewing Recurring Contracts] (4 min.)

====Additional Tutorials====
*[http://www.commitcrm.com/videos/employee_web_interface_tutorial_video.htm Web Interface For Employees] (6 min.)
*[http://www.commitcrm.com/videos/commit_activity_templates_video.htm Managing Activity Templates] (7 min.)
*[http://www.commitcrm.com/videos/commit_report_designer_tutorial_video.htm Report Designer Tutorial] (7 min.)

 
=====Other Videos=====

'''Manage Accounts:''' Your IT service business Customers, Contacts and Leads
*[http://www.commitcrm.com/videos/new_account.htm See how to add a new Account in Commit™] (33 sec.)

'''Manage IT Service Contracts:''' Block of Time, Block of Money, Block of Tickets, Date Range etc.
*[http://www.commitcrm.com/videos/new_contract.htm See how to create a new Contract for an Account] (1 min, 16 sec.)

'''Manage Tickets''' and increase control over all the open issues, incidents and problems.
*[http://www.commitcrm.com/videos/new_ticket.htm See how to create a new Ticket in Commit™] (45 sec.)
*[http://www.commitcrm.com/videos/charging_ticket.htm See how to add Charges to an open Ticket in Commit™] (42 sec.)

'''Increase Productivity by Dispatching''' the right technician to the right call and by measuring the technician's productivity.

[[Category:Getting Started]]
*[http://www.commitcrm.com/videos/dispatching_ticket.htm See how to dispatch an open service ticket to a technician] (44 sec.)

'''Organize Your Price List''' for products and services.
*[http://www.commitcrm.com/videos/new_labor_item.htm See how to create a new item in Commit™] (41 sec.)

'''Increase Revenues by Easily Entering Charges''' for labor services, expenses, products and parts.
*[http://www.commitcrm.com/videos/new_part_charge.htm See how to create a new Charge in Commit™] (25 sec.)
*[http://www.commitcrm.com/videos/charging_ticket.htm See how to add charges to a service Ticket] (42 sec.)

'''Eliminate paperwork! Easily Manage All Documents''' including MS-Word®, MS-Excel®, presentations, emails, scanned documents etc.
*[http://www.commitcrm.com/videos/importing%20_documents.htm See how to import existing documents folders and link them to your accounts] (45 sec.)

__NOTOC__

[[Category:Setup]]

API Reference Manual

2010-03-19T14:34:53Z

Reno: /* Document Fields */

{{usermanualsapidevelopersguide}}
==Intorduction==

Following is a detailed listing of fields per entity which can be added/updated using the API. The API parameters are the same when using the Programming API or the XML API.

The API allows you to add/update the following entities:
*[[#Account Fields|Accounts]]
*[[#Ticket Fields|Tickets]]
*[[#Charge Fields|Charges (and Contract-price Charges)]]
*[[#Item Fields|Items]]
*[[#History Note Fields|History Notes]]
*[[#Asset Fields|Assets]]
*[[#Calendar Fields|Calender]]
*[[#Opportunity Fields|Opportunities]]
*[[#Document Fields|Documents]]
*[[#Knowledge Base Article Fields|Knowledge Base Articles]]

All API functions may return error codes. You can find the possible error codes in:
*[[#Error Codes Description|Error Codes]]

In the following section you will find a detailed listing of the database fields. Each table includes the fields '''Display name''' (as shows in the application), the '''Database Field Name''' (internal database field identifier) and comments.

Note that when using XML formatted messages, the database field name refers to the name to be provided within the XML token. For example, when the field name is FLDSLPQUANTITY, the XML token should look like this:
<FLDSLPQUANTITY>10</FLDSLPQUANTITY>

The following table shows the data kind code when using XML or when using the API functions:

{| class="wikitable"
|-
! '''Application entity'''
! '''Table name'''
! '''Programming Code'''
! '''XML Data Kind Name'''
|-
| Accounts
| Cards
| 10
| ACCOUNT
|-
| Opportunities
| Opps
| 20
| OPPORTUNITY
|-
| Documents
| Docs
| 30
| DOCUMENT
|-
| Charges
| Slips
| 40
| CHARGE
|-
| Appointments/Tasks
| Events
| 50
| APPOINTMENT-OR-TASK
|-
| History Notes
| Notebook
| 60
| HISTORY-NOTE
|-
| Tickets
| Tickets
| 70
| TICKET
|-
| Items
| Items
| 80
| ITEM
|-
| Assets
| Assets
| 90
| ASSET
|-
| Knowledge Base
| KBArticles
| 100
| KBARTICLE
|}
You can find examples of adding and updating records in the database by using the database field in the [[API Code Samples]] section.

===Account Fields===
The following table lists the most important parameters for adding/updating Account
records.
Note slight differences when adding a main account vs. adding a secondary contact.

{| class="wikitable"
|-
! '''Field Name'''
! '''Database Field Name'''
! '''Comment'''
|-
| Account REC ID
| FLDCRDRECID
|The Account record ID (20 chars). The Account Rec ID can be taken from:
#Account Notes tab, at the bottom, rightclick the RecID field and use Copy. e.g. CRDVQYSOD1B4U4HZIQJJ
#Using ODBC to pull information from the database.
#From the Email Response when adding new Account with the API.
|-
| Account Manager
| FLDCRDASSIGNCARDID
| This field has two roles:
#When adding a main Account: The account manager should contain the ID of the Employee who is the account manager.
#When adding a secondary contact: 
This field should contain the ID of the main Account to which the secondary contacted is
added.
|-
|Company name
|FLDCRDCOMPANY
|
|-
|Contact: First & Last Name
|FLDCRDCONTACT
|
|-
| Assistant
| FLDCRDASSISTANT
|
|-
|Contract
|FLDCRDBCRECID
|The default Contract for this Account (not required)
|-
|Account Number
|FLDCRDCARDID2
|
|-
|ID
|FLDCRDCARDID3
|
|-
|Popup Message
|FLDCRDCARDMESSAGE
|
|-
| Address: Line1
| FLDCRDADDRESS1
|
|-
| Address: Line2
| FLDCRDADDRESS2
|
|-
| Address: Line3
| FLDCRDADDRESS3
|
|-
|Address: City
|FLDCRDCITY
|
|-
|Address: State
|FLDCRDCOUNTRY
|
|-
|Address: Country
|FLDCRDSTATE
|
|-
|Address: Zip
|FLDCRDZIP
|
|-
|Creation Date
|FLDCRDCREATEDATE
|Any date format, such as DD/MM/YYYY
|-
|Created by User
|FLDCRDCREATEUSERID
|Foreign Software Name which created the account
|-
|Dear
|FLDCRDDEAR
|
|-
|Department
|FLDCRDDEPARTMENT
|
|-
|Documents Store Directory
|FLDCRDDOCSFOLDER
|
|-
|E-Mail Address 1
|FLDCRDEMAIL1
|
|-
|E-Mail Address 2
|FLDCRDEMAIL2
|
|-
|Account Type
|FLDCRDENTITYKIND
|When adding a Main Account = 1 When adding a secondary contact = 5
|-
|Fax Number
|FLDCRDFAX1
|
|-
|Fax Number Extension
|FLDCRDFAXDESC1
|
|-
|File as
|FLDCRDFULLNAME
|
|-
|Type
|FLDCRDKIND
|
|-
|Last Name
|FLDCRDLASTNAME
|
|-
|Notes
|FLDCRDNOTES
|
|-
|Field
|FLDCRDPERSONID
|
|-
|Phone 1 Ext.
|FLDCRDPHNDESC1
|
|-
|Phone 2 Ext.
|FLDCRDPHNDESC2
|
|-
|Phone 3 Ext.
|FLDCRDPHNDESC3
|
|-
|Phone 4 Ext.
|FLDCRDPHNDESC4
|
|-
|Phone 1
|FLDCRDPHONE1
|
|-
|Phone 2
|FLDCRDPHONE2
|
|-
|Phone 3
|FLDCRDPHONE3
|
|-
|Phone 4
|FLDCRDPHONE4
|
|-
|Region
|FLDCRDREGIONCODE
|
|-
|Popup Message: Display Indication
|FLDCRDSHOWMESSAGE
|
|-
|Sub-Contact Code
|FLDCRDSUBCODE
|
|-
|Salutation
|FLDCRDSUFFIX
|
|-
|Tax1
|FLDCRDTAXCODE1
|
|-
|Tax2
|FLDCRDTAXCODE2
|
|-
|Notes
|FLDCRDNOTES
|
|-
|Title
|FLDCRDTITLE
|
|-
|Last Updated by
|FLDCRDUPDATEUSERID
|When performing updates on existing Account - pass the Foreign Software Name which performs the update.
|-
|Web Address 1
|FLDCRDURL1
|
|-
|Web Address 2
|FLDCRDURL2
|
|-
|Status
|FLDCRDUSER1
|
|-
|Field1
|FLDCRDUSER2
|
|-
|Field2
|FLDCRDUSER3
|
|-
|Field3
|FLDCRDUSER4
|
|-
|Field4
|FLDCRDUSER5
|
|}

===Ticket Fields===

The table below lists the most important Ticket parameters and behavior:

{| class="wikitable"
|-
! '''Field Name'''
! '''Database Field Name'''
! '''Comment'''
|-
| Account REC ID
| FLDTKTCARDID
|The Account record ID (20 chars). The Account Rec ID can be taken from:
#Account Notes tab, at the bottom by rightclicking the REC ID field and selecting Copy
#ODBC to pull information from the database
#The automated email response when adding a cnew Account with the API
|-
| Contact REC ID
| FLDTKTCONTACTID
|The Contact for this Account. If not provided, the main Contact for the Account is taken.
|-
| Contract REC ID
| FLDTKTBCRECID
|The Contract ID. If not supplied, will be taken from the Account's default contract.
|-
| Emp. REC ID
| FLDTKTWORKERID
|The worker ID to be linked to the Ticket. Must be an active employee. This is an optional parameter. If not passed, the system default will be used.
|-
| Priority
| FLDTKTPRIORITY
| The ticket priority. If not passed in the transaction, the default value for new Tickets will be used.
Immediate = 10 High = 20 Normal = 30 Low = 40 Not Applicable= 50
|-
| Ticket Number
| FLDTKTTICKETNO
| The Ticket number. If passed, must be an existing Ticket, and this will update the Ticket with the details in the transaction.
|-
|Description
|FLDTKTPROBLEM
|This is the Ticket Description. This is a mandatory field, which must contain text.
|-
|Ticket Type
|FLDTKTKIND
|Ticket Type (optional). The Ticket Type string should be passed. If not provided, default is used.
|-
|Source
|FLDTKTSOURCE
|
|-
|Estimated Duration Time
|FLDTKTSCHEDLENESTIM
|Estimated duration time for the Ticket in minutes.
|-
|Show Ticket in Dispatcher
|FLDTKTFORDISPATCH
|Possible values: Yes/No
|-
|Status
|FLDTKTSTATUS
|The Ticket Status (optional). 
Possible values: 
New = 100 
Pending = 200 
Scheduled = 300 
In-House Service = 400 
On-Site Service = 500 
Laboratory Service = 600 
Hold = 700 
Other = 800 
Canceled = 900 
Completed = 1000
|-
|Created by User
|FLDTKTCREATEUSER
|Should contain the external software name which created the Ticket
|-
|Due Date
|FLDTKTDUEDATETIME
|Due date for the Ticket. Should be passed in date format. e.g. MM/DD/YYYY
|-
|Resolution
|FLDTKTSOLUTION
|Ticket resolution text
|}

===Charge Fields===
The table below lists the most important Charge parameters and behavior.

Contract-price Charges have some special characteristics (see comments marked by * in
the table below):

{| class="wikitable"
|-
! '''Field Name'''
! '''Database Field Name'''
! '''Comment'''
|-
| Record ID
| FLDSLPRECID
|The Charge record ID. If provided, the existing Charge will be updated. Otherwise, this will be
added as a new Charge.
|-
| Charge Source
| FLDSLPSOURCERECID
|The Charge source is the entity for which the charge is created. 
Possible values:
*Linked Contract RecID (for Contract-price Charges). Cannot be the "System Global Contract".
**Passing the Contract RecID indicates that this is a Contract-price charge.
*Entity RecID from which the charge is created (for example when creating a charge from an Appointment or Task).
|-
| Account REC ID
| FLDSLPCARDID
|The Account record ID (20 chars). The Account REC ID can be taken from:
#Account Notes tab, at the bottom by rightclicking the REC ID field and selecting Copy
#ODBC to pull information from the database
#The automated email response when adding a new Account with the API
|-
| Employee REC ID
| FLDSLPWORKERID
| The worker record ID to be linked to the Charge. Must be an active employee. This is an optional parameter. If not passed, the system default will be used.
|-
| Charged Item
| FLDSLPITEMID
| The Item Record ID to be linked to the Charge. This is a mandatory field.
*For Contract-price Charge can be only Fixed-Price, Unit-based Item.
|-
| Contract REC ID
| FLDSLPBCRECID
| The contract record ID (must be a Contract of the Account)
|-
|Ticket REC ID
|FLDSLPTICKETID
|The Ticket ID to be linked to the Charge.
*Not relevant for Contract-price Charge
|-
|Date
|FLDSLPSLIPDATE
|The date for the Charge. This is an optional parameter. If not provided, the current date will
be used. Should be passed in date format. e.g. MM/DD/YYYY
|-
|Description
|FLDSLPDESC
|The Charge Description. If not provided, will be taken from the Item's description.
|-
|Units/Hours
|FLDSLPQUANTITY
|This is the quantity of hours/units
|-
|Adjust Amount
|FLDSLPADJUSTAMOUNT
|Discount/Markup amount. Positive number means Markup, negative number means Discount.
|-
|Adjust Percent
|FLDSLPADJUSTPERCENT
|Discount/Markup in percentage, must be between (-100) - 100. Positive number means Markup, negative number means Discount.
|-
|From Time
|FLDSLPSTARTTIME
|From time for labor Charges e.g. 12:06
*Not relevant for Contract-price Charge
|-
|To Time
|FLDSLPENDTIME
|From time for labor Charges e.g. 14:50
* Not relevant for Contract-price Charge
|-
|Price/Rate
|FLDSLPPRICE
|If not provided, the price is taken from the Item.
|-
| Billable
| FLDSLPBILLKIND
| B - Billable 
N - Not Billable 
If not provided, will be set according to the Contract type.
|-
| Billed
| FLDSLPSTAGE
| D - Draft
B - Billed
|-
| Field1
| FLDSLPUSER1
| User defined field
|-
| Create User
| FLDSLPCREATEUSER
| External software name which created the Charge
|}

===Item Fields===

The table below lists the most important Item parameters and behavior:

{| class="wikitable"
|-
! '''Field Name'''
! '''Database Field Name'''
! '''Comment'''
|-
| Record ID
| FLDITMRECID
|The Item record ID. If provided, the existing item will be updated. Otherwise, this will be added as a new item.
|-
| Item Group
| FLDITMITEMTYPEGROUP
|The Item Group to be linked to the Charge. This is a mandatory field: 
F - Labor (Fee) 
X - Expense 
P - Part
|-
| Item Code
| FLDITMITEMNO
|The item code is a mandatory field
|-
| Item Name
| FLDITMNAME
| The item name is a mandatory field
|-
| Price Source
| FLDITMPRICESOURCE
| F - Fixed Price 
W - by Employee Rate
|-
| Price per Hour/Unit
| FLDITMUNITISHOUR
| This field indicated whether the price is unitbased or hours-based. 
Y - by Hours 
N - by Units 
This is an optional field, depending on the Item Group. For example, if the item group is Labor, and Price Source is By Employee, the value will always be by hours
|-
|Price
|FLDITMUNITPRICE
|Must be a valid numeric value
|-
|Cost
|FLDITMSTANDARDCOST
|The date for the Charge. This is an optional parameter. If not provided, the current date will
be used. Should be passed in date format. e.g. MM/DD/YYYY
|-
|Taxes
|FLDITMTAXCODE1 
FLDITMTAXCODE2 
FLDITMTAXCODE3
|You can pass up to 3 different tax codes.
|-
|Description by Name
|FLDITMDESCBYNAME
|Y - take the description from the name field 
N - take the description from the Description field
|-
|Description
|FLDITMDESC
|If not provided, the description is taken from the name.
|-
|Suspend
|FLDITMSUSPENDED
|Indicated whether this item is currently suspended: 
Y - yes 
N - no
|-
|Notes
|FLDITMNOTES
|
|-
|Field1
|FLDITMUSER1
|User defined field
|-
|Create User
|FLDITMCREATEUSER
|External software name which created the Charge
|-
| Created by User
| FLDTKTCREATEUSER
| Should contain the external software name which created the Ticket
|}

===History Note Fields===
The table below lists the most important History Note parameters and behavior:

{| class="wikitable"
|-
! '''Field Name'''
! '''Database Field Name'''
! '''Comment'''
|-
| Record ID
| FLDHISRECID
|The History Note record ID. If provided, the existing History Note will be updated. otherwise, this will be added as a new History Note.
|-
| Date
| FLDHISNOTEDATETIME
|Any date format, such as DD/MM/YYYY
|-
| Description
| FLDHISDESCRIPTION
| The Description text
|-
| Opportunity/Ticket/Contract
| FLDHISLINKRECID
| Link to Opportunity or Ticket or Contract
|-
| Field
| FLDHISUSER1
| User defined field
|-
| About
| FLDHISKIND
| Optional field
|-
|Employee
|FLDHISWORKERID
|The worker ID to be linked to the Ticket. Must be an active employee. This is an optional parameter. If not passed, the system default will be used.
|-
|Account
|FLDHISCARDID
|The Account record ID (20 chars). The Account Rec ID can be taken from:
#Account Notes tab, at the bottom, right-click the REC ID field and use Copy. e.g. CRDVQYSOD1B4U4HZIQJJ
#Using ODBC to pull information from the database
#From the Email Response when adding new Account with the API
|-
|Contact
|FLDHISCONTACTID
|The Contact for this Account. If not provided, the main Contact for the Account is taken.
|-
|Document
|FLDHISDOCID
|Linked Document ID, can be taken from the Document Properties window (right-click RecID and use Copy), or using the ODBC to pull information from the database.
|-
|Created by User
|FLDHISCREATEUSER
|Name of the external software which created this History Note
|}

===Asset Fields===
The table below lists the most important Asset parameters and behavior:

{| class="wikitable"
|-
! '''Field Name'''
! '''Database Field Name'''
! '''Comment'''
|-
| Asset Code
| FLDASTASSETCODE
|If an existing Asset Code is provided, then existing Asset is updated. Otherwise a new Asset is added.
|-
| Asset Type
| FLDASTASSETTYPE
|The Type field is mandatory: 
Hardware = H 
Software = S 
Other = T
|-
| Asset Name
| FLDASTNAME
|
|-
| Status
| FLDASTSTATUS
| Mandatory field. 
Active = A 
Not Active = N 
If not provided, default Active is used.
|-
| Record ID
| FLDASTRECID
| If provided, must exist in the database. Ignored if empty
|-
| Serial No.
| FLDASTSERIALNO
|
|-
|Account
|FLDASTACCRECID
|The Account which is linked to the Asset
|-
|Contact
|FLDASTCONTACTRECID
|The Contact for this Account. If not provided, the main Contact for the Account is taken.
|-
|Created by user
|FLDASTCREATEUSER
|Name of external software which created this Asset
|-
|Purchase Date
|FLDASTCUSTPURDATE
|Any date format, such as DD/MM/YYYY
|-
|Purchased From Us
|FLDASTCUSTPURFROMUS
|Possible values: Y/N. 
If not provided, default value Y is used.
|-
| Purchase Invoice #
| FLDASTCUSTPUROURINV
|
|-
| Customer PO
| FLDASTCUSTPURPO
|
|-
| Purchase Price
| FLDASTCUSTPURPRICE
|
|-
| Delivered Date
| FLDASTDELIVEDATE
|
|-
| Description
| FLDASTDESC
|
|-
| Installed By
| FLDASTINSTALBY
|
|-
| Installed Date
| FLDASTINSTALDATE
|
|-
| License Codes
| FLDASTLICENSECODE
|
|-
| License Keys
| FLDASTLICENSEKEY
|
|-
| License Notes
| FLDASTLICENSENOTES
|
|-
| Location
| FLDASTLOCATION
|
|-
| Manufacturer
| FLDASTMANUFACTURER
|
|-
| Mnf Serial No.
| FLDASTMNFSERIALNO
|
|-
| Model
| FLDASTMODEL
|
|-
| Notes
| FLDASTNOTES
|
|-
| Quantity
| FLDASTQUANTITY
| If not provided, default value of 1 is used.
|-
| Last Update By
| FLDASTUPDATEUSER
| Name of externals software which performed the update
|-
| Field1
| FLDASTUSER1
| User defined field
|-
| Field2
| FLDASTUSER2
| User defined field
|-
| Field3
| FLDASTUSER3
| User defined field
|-
| Field4
| FLDASTUSER4
| User defined field
|-
| Field5
| FLDASTUSER5
| User defined field
|-
| Date1
| FLDASTUSERDATE1
| User defined field
|-
| Number1
| FLDASTUSERNUMBER1
| User defined field
|-
| Vendor Purchased Date
| FLDASTVENDORDATEPURC
|
|-
| Vendor Invoice #
| FLDASTVENDORINVNO
|
|-
| Vendor PO
| FLDASTVENDOROURPO
|
|-
| Vendor Price
| FLDASTVENDORPRICE
|
|-
| Vendor
| FLDASTVENDORRECID
|
|-
| Vendor Serial No.
| FLDASTVENDORSERNO
|
|-
| Vendor Warranty Exp. Date
| FLDASTVENDORWARREXP
| Any date format, such as DD/MM/YYYY
|-
| Version
| FLDASTVERSION
|
|-
| Warranty/License Exp.
| FLDASTWARREXPDATE
| Any date format, such as DD/MM/YYYY
|-
| Date
|
|
|}

===Calendar Fields===
The table below lists the most important Calendar parameters and behavior:

{| class="wikitable"
|-
! '''Field Name'''
! '''Database Field Name'''
! '''Comment'''
|-
| Record ID
| FLDEVTRECID
|The Appointment/Task record ID. If provided, the existing entity will be updated. Otherwise, this
will be added as a new Appointment/Task.
|-
| Event Type
| FLDEVTWRITETOID
|The Event type is a mandatory field. 
Appointment = 1 
Task = 2
|-
| Employee
| FLDEVTWORKERID
| The Task/Appointment owner (for private events)
|-
| Private: User
| FLDEVTPRIVATEID
| Possible values: Y/N 
If an Employee was set, this field must be Y
|-
| Account
| FLDEVTCARDID
| The Account record ID (20 chars). The Account REC ID can be taken from:
#Account Notes tab, at the bottom by rightclicking
the REC ID field and selecting Copy
#ODBC to pull information from the database
#The automated email response when adding a
new Account with the API
|-
| Contact
| FLDEVTCONTACTID
| The Contact for this Account. If not provided, the main Contact for the Account is taken.
|-
|Document
|FLDEVTDOCID
|Linked Document ID, can be taken from the Document Properties window (right-click RecID and use Copy), or using the ODBC to pull information from the database.
|-
|Done Indication
|FLDEVTDONE
|Possible values: Y/N
|-
|Date
|FLDEVTEVENTDATE
|The Appointment/Task date is a mandatory field of Any date format, such as DD/MM/YYYY. If not
provided, the current date will be used.
|-
|Description
|FLDEVTFREETEXT
|
|-
|Time: Start
|FLDEVTFROMTIME
|Mandatory field
|-
| Time: End
| FLDEVTTOTIME
| Relevant only for Appointments. If this parameter is not provided, 30 min. interval from Start Time is used.
|-
| Opportunity/Ticket
| FLDEVTLINKRECID
| Linked Ticket/Opportunity/Contract/Asset
|-
| Field1
| FLDEVTFAMILY
| User Defined field
|-
| Field2
| FLDEVTACTION
| User Defined field
|-
| Field3
| FLDEVTPLACE
| User Defined field
|-
| Field4
| FLDEVTPLACE1
| User Defined field
|-
| Field5
| FLDEVTPLACE2
| User Defined field
|-
| Created by User
| FLDEVTCREATEUSERID
| Name of external software which created the event
|-
| Last Update: By User
| FLDEVTUPDATEUSER
| Name of external software which updated the
event
|}

===Opportunity Fields===
The table below lists the most important Opportunity parameters and behavior:

{| class="wikitable"
|-
! '''Field Name'''
! '''Database Field Name'''
! '''Comment'''
|-
| Record ID
| FLDOPPRECID
| The Opportunity record ID. If provided, the existing Opportunity will be updated. Otherwise, this will be added as a new Opportunity.
|-
| Opportunity Name
| FLDOPPNAME
| Mandatory field.
|-
| Opportunity ID
| FLDOPPUSERID
| Optional (Oppty ID)
|-
| Account
| FLDOPPCARDID
| The Account record ID (20 chars). The Account REC ID can be taken from:
#Account Notes tab, at the bottom by right-clicking the REC ID field and selecting Copy
#ODBC to pull information from the database
#The automated email response when adding a new Account with the API
|-
| Contact
| FLDEVTCONTACTID
| The Contact for this Account. If not provided, the main Contact for the Account is taken.
|-
| Source
| FLDOPPSOURCE
|
|-
|Document
|FLDEVTDOCID
|Linked Document ID, can be taken from the Document Properties window (right-click RecID and use Copy), or using the ODBC to pull information from the database.
|-
|Done Indication
|FLDEVTDONE
|Possible values: Y/N
|-
|Close Date
|FLDOPPCLOSEDATE
|
|-
|Manager
|FLDOPPWORKERID
|The Manager's REC ID
|-
|Open Date
|FLDOPPOPENDATE
|
|-
| Close By Date
| FLDOPPESTDATE
| Opportunity must be closed by this date
|-
| Amount
| FLDOPPAMOUNT
|
|-
| Probability %
| FLDOPPPROBABILITY
|
|-
| Stage
| FLDOPPSTAGE
|
|-
| Status
| FLDOPPSTATUS
|
|-
| Closing Amount
| FLDOPPCLOSEAMOUNT
|
|-
| Description
| FLDOPPDESCRIPTION
|
|-
| Opportunity Type
| FLDOPPKIND
|
|-
| Opportunity Reason
| FLDOPPREASON
|
|-
| Note
| FLDOPPNOTES
|
|-
| Territory
| FLDOPPREGION
|
|-
| Field1
| FLDEVTFAMILY
| User Defined field
|-
| Field2
| FLDEVTACTION
| User Defined field
|-
| Field3
| FLDEVTPLACE
| User Defined field
|-
| Created by User
| FLDEVTCREATEUSERID
| Name of external software which created the event
|-
| Last Update: By User
| FLDEVTUPDATEUSER
| Name of external software which updated the event
|}

===Document Fields===
The table below lists the Document parameters and behavior:

{| class="wikitable"
|-
! '''Field Name'''
! '''Database Field Name'''
! '''Comment'''
|-
| Record ID
| FLDDOCRECID
| The Document record ID. If provided, the existing Document will be updated. Otherwise, this will be added as a new Document.
|-
| Document Date
| FLDDOCDOCDATE
| The date for the Document. This is an optional parameter. If not provided, or if the value is illegal, the current date will be used. Should be passed in date format. e.g. MM/DD/YYYY
|-
| Subject
| FLDDOCDOCUMENTDESC
|
|-
| Linked Record
| FLDDOCLINKRECID
| The RECID of a linked object. Each Document can be linked to one of the following objects:
*Ticket
*Contract
*Opportunity
*Knowledge Base Article
*Asset
The Record ID (20 chars) can be taken from:
#Object's Notes tab, at the bottom by right-clicking the REC ID field and selecting Copy
#ODBC to pull information from the database
#The automated email response when adding a new object with the API.
|-
| Account Rec ID
| FLDDOCCARDID
| The Account record ID (20 chars). The Account REC ID can be taken from:
#Account Notes tab, at the bottom by right-clicking the REC ID field and selecting Copy
#ODBC to pull information from the database
#The automated email response when adding a new Account with the API
|-
| Contact REC ID
| FLDDOCCONTACTID
| The Contact for this Account. If not provided, the main Contact for the Account is taken.
|-
|Field1
|FLDDOCTRANSPORT
|User Defined field
|-
|Field2
|FLDDOCFOLDER
|User Defined field
|-
|Field3
|FLDDOCUMENTPLACE
|User Defined field
|-
|File Path + File name
|FLDDOCDOCUMENTNAME
|The Document path
|-
|Category
|FLDDOCTREEID
|The category record ID should be taken from the database table called TreeTbl which contains the Category tree
|-
| Employee REC ID
| FLDDOCWORKERID
| The worker record ID to be linked to the Document. Must be an active employee. This is an optional parameter. If not passed, the system default will be used.
|-
| Created by User
| FLDDOCCREATEUSER
| Name of external software which created the document
|-
| Last Update: By User
| FLDDOCUPDATEUSER
| Name of external software which updated the document
|}

===Knowledge Base Article Fields===
The table below lists the Knowledge Base Article parameters and behavior:

{| class="wikitable"
|-
! '''Field Name'''
! '''Database Field Name'''
! '''Comment'''
|-
| Record ID
| FLDKBARECID
| The Article record ID. If provided, the existing Article will be updated. Otherwise, this will be added as a new Article.
|-
| Document Date
| FLDKBACREATEDATE
| The date for the Document. This is an optional parameter. If not provided, or if the value is illegal, the current date will be used. Should be passed in date format. e.g. MM/DD/YYYY
|-
| Title
| FLDKBATITLE
|
|-
| Problem
| FLDKBAPROBLEM
|
|-
| Solution
| FLDKBASOLUTION
|
|-
| Status
| FLDKBASTATUS
| Possible values:
*DRAFT = 'D'
*PUBLISHED = 'P'
*OBSOLETE = 'O'
|-
|Category
|FLDKBACATEGORY
|
|-
|Public
|FLDKBAISPUBLIC
|Is the Document public. 
Possible values: 
*'Y' = Yes
*'N' = No
|-
|Created by User
|FLDDOCCREATEUSER
|Name of external software which created the document
|-
|Last Update: By User
|FLDDOCUPDATEUSER
|Name of external software which updated the document
|}

===Error Codes Description===
These error codes are returned when calling the CmtGetDescriptionByStatus function: 
'''1000''' CmtDbEng.dll not found. 
'''1001''' Invalid value for the Data Kind value. 
'''1002''' Invalid DATA buffer received. Make sure you have allocated the buffer correctly and
that you have passed the correct buffer length. 
'''1003''' Invalid MAP buffer received. Make sure you have allocated the buffer correctly and
that you have passed the correct buffer length. 
'''1004''' Invalid REC ID buffer received. Make sure you have allocated the buffer correctly
and that you have passed the correct buffer length. 
'''1005''' Invalid LOG buffer received. Make sure you've allocated the buffer correctly and
that you've passed the correct buffer length. 
'''1006''' Invalid REC ID buffer received. It should be at least 20 characters. 
'''1007''' Invalid external software name received. Specify a unique name that identifies your
software. 
'''1008''' Cannot process the transaction. Make sure to call the INIT procedure at least once
prior to sending transactions for processing. 
'''1009''' Path specified for Commit DB folder not found. 
'''1010''' Path specified for Commit DB folder found, but its contents do not reflect a valid DB
folder. 
'''1011''' The RED ID received for the employee/user was not found in Commit, is invalid or is
related to an inactive employee record. 
'''1012''' Error registering software. 
'''1013''' Software name is missing. Make sure you specify a name that identifies your
software. 
'''1014''' Software name is less than 3 characters long. Make sure you enter a software name
that has 3 to 15 characters. 
'''1015''' Software name is too long. Make sure your software name has 3 to 15 characters. 
'''1100''' Database access error. 

General error codes, returned when calling the functions CmtGetDescriptionByCode: 
'''50000''' The data is not correct for its type. 
'''50001''' The field value has been truncated due to the field length in the database. 
'''50002''' The insert operation Failed because the REC ID already existed in the database. 
'''50003''' Failed to update Record since it is being updated by another user. 
'''50103''' Illegal REC ID. 
'''50104''' REC ID Creation failed. 
'''50105''' Illegal Sub-Contact REC ID. 
'''50106''' Illegal Contract REC ID. 
'''50107''' Illegal Employee REC ID. 
'''50108''' Illegal Ticket REC ID. 
'''50109''' Illegal Account REC ID. 
'''50110''' Illegal data for that Contract. 
'''50111''' This Employee is not active. 
'''50112''' Illegal Document REC ID. 
'''50113''' Illegal linked object REC ID. 
'''50114''' Employee not found. 
'''50115''' Some mandatory fields have no values. 
'''51000''' Illegal kind of Account entity. 
'''51001''' Account Manager not found. 
'''51002''' The REC ID of the Account Manager is illegal. 
'''51003''' Illegal tax code. 
'''51004''' This code does not exist in Commit. 
'''52000''' Illegal kind of event. 
'''52001''' Illegal start time. 
'''52002''' Illegal end time. 
'''52003''' Illegal event date. 
'''52004''' The field Reminder1 has Illegal Value. 
'''52005''' The amount in the field has an illegal value. 
'''52006''' The Field Remider1:Units has Illegal Value. 
'''52007''' The Field Remider2:Active has Illegal Value. 
'''52008''' The Field Remider2:Amount has Illegal Value. 
'''52009''' The Field Remider2:Units has Illegal Value. 
'''52010''' Illegal employee REC ID. 
'''52011''' Error occurred while updating the Task/Appointment employee field. 
'''54000''' Illegal Ticket open date. 
'''54001''' Illegal Ticket close date. 
'''54002''' Illegal Ticket code area. 
'''54004''' Illegal Ticket priority. 
'''54005''' Illegal Ticket status. 
'''54006''' The Ticket Account was not found in the database. 
'''54007''' The Ticket Account Manager was not ound in the database. 
'''54008''' This code does not exist in Commit. 
'''54009''' This code does not exist in Commit. 
'''54010''' This code does not exist in Commit. 
'''54011''' This code does not exist in Commit. 
'''54012''' This code does not exist in Commit. 
'''55000''' Illegal charge date. 
'''55001''' Illegal charge REC ID. 
'''55002''' Illegal start date. 
'''55003''' Illegal start time. 
'''55004''' Illegal amount entered for hours. 
'''55005''' Illegal quantity. 
'''55006''' Illegal price. 
'''55007''' Illegal total. 
'''55008''' Illegal value in the Adjust Amount field. 
'''55009''' Illegal value in the Adjust Percent. 
'''55010''' The Discount/Markup field has an illegal value. 
'''55011''' Illegal value in the Adjust Kind field. 
'''55012''' Illegal bill total. 
'''55013''' You can not create a charge for a suspended item. 
'''55014''' Item was not found in Commit. 
'''55015''' This code does not exist in Commit. 
'''55016''' This code does not exists in Commit. 
'''55017''' This Code does not exist in Commit. 
'''55018''' This Code does not exist in Commit. 
'''55019''' This Code does not exist in Commit. 
'''55020''' This Code does not exist in Commit. 
'''55021''' This Code does not exist in Commit. 
'''56000''' Illegal item code. 
'''56001''' The field that indicates the item group type has an illegal value. 
'''56002''' The field that indicates if the Item is suspended has an illegal value. 
'''56003''' Illegal value of The field that indicate if the item is suspended. 
'''56004''' Mismatch found between the fields price and price source. 
'''56005''' Illegal cost. 
'''56006''' Mismatch found between the fields cost and item group type. 
'''56007''' The field that indicates if the charge is by unit or by hours has an illegal value. 
'''56008''' Illegal value in the Description. 
'''56009''' The field that indicates the item type has an illegal value. 
'''57000''' This Code does not exist in Commit. 
'''58000''' Illegal date time. 
'''58001''' The Description field was not found. 
'''58002''' The field kind was not found. 
'''58003''' The Account member was not found. 
'''59000''' This code does not exists in Commit. 
'''59001''' This Code does not exist in Commit. 
'''59002''' This Code does not exist in Commit. 
'''59003''' This Code does not exist in Commit. 
'''59004''' This Code does not exist in Commit. 
'''59005''' This Code does not exist in Commit. 
'''60000''' Invalid web user record ID number. 
'''60001''' This customer web user is not active. 
'''60002''' This user is not a customer. 

==See Also==
*[[Commit API Developers Guide]]
*[[API Code Samples]]
[[Category:User Manuals]]
[[Category:Integration]]

__NOTOC__

File:Htmlform.jpg

2010-03-15T22:06:30Z

Reno: uploaded a new version of "File:Htmlform.jpg"

KB: Using PHP To Automatically Generate and Email XML Transactions to Email Connector

2010-03-15T22:05:31Z

Reno: Created page with '==Introduction== The information on this page will show you the basic steps you need to follow to implement web forms on your Web site that will trigger insert and update events …'

==Introduction==
The information on this page will show you the basic steps you need to follow to implement web forms on your Web site that will trigger insert and update events in your CommitCRM database. For example, you can automatically convert contact forms filled by visitor to your Web site into new Account in CommitCRM.
This helps automating your work flow and saves the time it takes to manually add the account records.

The examples described below correspond to the XML samples described in the [[KB:_Automatically_Creating_New_Accounts_for_Web_Site_Visitors|Automatically Creating New Accounts for Web Site Visitors]] article, effectively completing the automation of the creation of new CommitCRM accounts, this should be considered as "The next step…". If you haven't read the first part, we recommend that you do this prior to continuing to read this article.

Note: This article is using PHP as the scripting language to send the XML API transaction to CommitCRM. It shouldn't be too hard to implement this with other scripting languages such as ASP.

The methods described on this article have some special requirements that must be satisfied prior to applying the information from this article. Here are the requirements:
*Web Server (Apache, Microsoft® IIS, etc.).
*PHP Support (we only tested the following with PHP5, though an earlier version may work as well).
*Email Access (Used by the web server to email the XML email transactions to CommitCRM).
*Commit Email Connector License.

 
==HTML Forms==
By using an HTML Web Form, you can allow your customers to enter the basic contact information into the web form where that information can then be automatically converted to CommitCRM XML formatting (used as an a CommitCRM API transaction, explained below), and emailed automatically to the system to be applied to the CommitCRM database as a new customer account. The way this part works is that the customer enters the information into a basic HTML form, and that form submits the information to a PHP script that processes the information.

In this sample, we're going to gather four different pieces of basic customer contact information that can be used to identify the customer until complete information is gathered from the customer. If you have some experience editing HTML, XML and PHP, then you can edit the samples in this page to your own preferences, and gather any information you require from your customers with the Web form. The information we're going to gather is as follows:
*Name
*Company Name
*Email Address
*Phone Number
[[File:Htmlform.jpg|400 px|center]]
 

===Disclaimer===
This document contains programming examples.
Commit Business Solutions Ltd ("Commit") grants you a nonexclusive copyright license to use all programming code examples from which you can generate similar function tailored to your own specific needs. All sample code is provided by Commit for illustrative purposes only. These examples have not been thoroughly tested under all conditions. Commit, therefore, cannot guarantee or imply reliability, serviceability, or function of these programs. All programs and code samples contained herein are provided to you "AS IS" without any warranties of any kind. The implied warranties of non-infringement, merchantability and fitness for a particular purpose are expressly disclaimed.

Here's a sample HTML code that will request and submit the information from the customer to a PHP script called XML_Processor.php, located in the same folder as this HTML script.
You can open a text file, copy that sample code, save it (like test-form.html ), upload to your Web server and navigate your browser to this file.
===HTML Sample===
<pre>
<html><body>




<form method="post" action="XML_Processor.php">



<table bgcolor=#ffffcc align=center>
<tr><td colspan=2>Contact us using this form:</td></tr>
<tr><td>* Name:</td><td><input size=25 name="cntct"></td></tr>
<tr><td>* Email:</td><td><input size=25 name="email"></td></tr>
<tr><td>* Company:</td><td><input size=25 name="cmpny"></td></tr>
<tr><td>* Phone:</td><td><input size=25 name="phone"></td></tr>
<tr><td colspan=2 align=center><input type=submit name="send" value="Submit"></td></tr>
<tr><td colspan=2 align=center>A * indicates a field is required</td></tr>
</table>
</form>
</body>
</html>
</pre>

 
==PHP XML Processor Script==
Using PHP you can have the web server do all the work needed to take the information submitted by the web form to the PHP script, and automatically create an XML transaction based on that information and email it to the Commit Email Connector, to be applied directly to the CommitCRM database.

The PHP script below has been designed to receive the information entered in the sample web form discussed above, and insert the information into the corresponding part of the XML template. Before using the script, please read the script notes, and adjust the first section to reflect the information needed to send the email message and Insert the API password you configured to be used with Commit API By Email ([[API_by_Email_and_MSP_Integration#API_by_Email_.28XML_Formatted_Emails.29|click here for more info on API settings]]).

Please review this script, and adjust it freely to your own preferences so that it can facilitate the transfer of the information you need it to transfer to CommitCRM; however, editing this script would require experience in PHP scripting.

'''Please Note: This script requires PHP5 to be installed on the Web Server.'''

Copy the Below Script to an empty text file called '''XML_Processor.php''' and save it in the same folder as the HTML form.
<pre>
<?php
//=========================== Notes =================================
//This script is meant for basic CommitCRM database manipulation. The
//samples included here can be adjusted to include different data in the
//transaction; more information on using XML can be found in this link:
//http://www.commitcrm.com/wiki/API_Code_Samples#XML_samples.
//We suggest adding mechanisms to the web form to ensure that the user
//cannot submit the form without first passing a Human Verification test
//on the same page. Samples for tests like this are available on the
//Internet, and very helpful in preventing spammers from teaching their
//spam systems how to fill your database with fictitious accounts.

//======================================================================
//======================================================================
//======PLEASE EDIT THIS SECTION TO REFLECT YOUR EMAIL CONNECTOR========
//======================================================================
//======================================================================
//Email Envelope - Edit these values to reflect your CommitCRM Mailbox.
$email_to = 'EmailConnector@YourBusiness.com';
//This line represents the Email Subject to be used on each transaction=
$subject = 'Web Form To CommitCRM Account Email';
//This line should reflect the email address that sends the webform=====
$header = 'From: Webform@YourBusiness.com';
//This line tells the script the API Password for your Email Connector==
$apipasswd = 'your_API_passwd';
//XML Transaction Responses get sent to this email address==============
$readdress = 'Email_Address_To_Send_Responses_to';

//======================================================================
//======================================================================
//=======Constant variables - Do not edit below this comment!===========
//======================================================================
//======================================================================
$company = $_POST['company'];
$contact = $_POST['contact'];
$phone = $_POST['phone'];
$eaddress = $_POST['email'];

//======================================================================
//This section verifies that all data has been entered; if the data has
//been entered, then the script will notify your customer to hit the
//back button.
if ($company && $contact && $phone && $eaddress) {
echo "Thank you for submitting your form. You may submit email service requests to our Support Center at:";
echo $email_to;
} else {
exit("You have not filled out all the required fields. Place hit your back button and fill out all the required fields.");
}

$xml = '<?xml version="1.0" ?>
<?commitcrmxml version = "1.0" ?>
<CommitCRMTransaction>
<ExternalApplicationName>WebsiteSignup</ExternalApplicationName>
<SendResponseToEmail>' . $readdress . '</SendResponseToEmail>
<Password>' . $apipasswd . '</Password>
<ReturnTransactionID>WebForm - New Account</ReturnTransactionID>
<DataKind>ACCOUNT</DataKind>
<RecordData>
<FLDCRDCOMPANY>' . $company . '</FLDCRDCOMPANY>
<FLDCRDCONTACT>' . $contact . '</FLDCRDCONTACT>
<FLDCRDPHONE1>' . $phone . '</FLDCRDPHONE1>
<FLDCRDEMAIL1>' . $eaddress . '</FLDCRDEMAIL1>
</RecordData>
</CommitCRMTransaction>';

mail($email_to, $subject, $xml, $header);

?>
</pre>

 
==The Next Step==
Once your customer has successfully created his/her own account, they can send email messages to your support email address (i.e. the [[Email_Connector#Incoming_Email_Settings|Public Email Address]]), which is processed automatically by the Commit Email Connector. Commit Email Connector will automatically convert the email message into a service ticket for the newly created account. Please note that [[Email_Connector#Email_to_Ticket_Setting|Email2Ticket]] will only work if the ticket is sent from the email account that the customer specified in the Web Form.

 
==Summary==
If you've followed this tutorial, then you've successfully facilitated a basic system which allows your new customers to create their own accounts using:
*An HTML Form which gathers basic account info.
*A PHP form which processes the info and emails to CommitCRM.
*The Commit Email Connector which receives and applies the new information.

Associating your customer with CommitCRM opens the door to offering automated service tickets ([[Email Connector|Commit Email Connector]]) and personal account monitoring abilities to your customers ([[Web_Interface|Commit Web Interface for Customers]]).

==See Also==
[[KB:_Automatically_Creating_New_Accounts_for_Web_Site_Visitors|Automatically Creating New Accounts for Web Site Visitors]] 
[[API_Code_Samples#XML_samples|API Code Samples]] 
[[Email_Templates|Email Templates]] 
[[KB:_Emailing_your_customers_using_Mail_Merge|Emailing your customers using Mail Merge]] 
[[Web_Interface|Commit Web Interface]] 
[[Email Connector|Commit Email Connector]] 
[http://www.php.net/manual/en/index.php PHP5 Manual] 
[http://devzone.zend.com/article/2387 XML and PHP5 Tutorial] 
[[Category:KB|PHP]]

File:Htmlform.jpg

2010-03-15T21:55:49Z

Reno:

KB: Automatically Creating New Accounts for Web Site Visitors

2010-03-11T19:51:56Z

Reno: /* See Also */

==Introduction==
Many businesses have a Web form on their Web site that is designed to capture the contact details of potential customers. The Commit Email Connector can help automating this process by automatically processing emails sent by your Web forms and creating new CommitCRM Accounts for them.

How does this work? Using the Commit Email Connector’s Advanced XML processing features, the system can receive emails containing XML transactions from a web form, and perform the actions requested in the transaction, on the CommitCRM database. Once an account is created in the system, customers can submit their own tickets using the Commit Email Connector’s [[Email_Connector#Email_to_Ticket_Settings|Email to ticket feature]]. The Email to Ticket feature helps by taking emails sent to your Public Email Address using the same email address they filled in the Web form. Commit Email Connector will identify them by their email and will open a new ticket for their account. You can learn more about this by reading more about the Email to Ticket feature [[Email_Connector#Email_to_Ticket_Settings|here]].

Web forms which are designed in standard (PHP, Perl, CGI, Etc.) web form formats allow you to gather different details from the person browsing pages, and turn them into script variables which can be automatically placed in the XML template in their correct place, and email the outputted XML transaction in plain text format to the Commit Email Connector, to be processed and then added as a new customer.

 
==Configuring the Commit Email Connector for XML Transactions==
Instructions for configuring the basic settings for the Commit Email Connector’s API by Email can be found [[API_by_Email_and_MSP_Integration#API_by_Email_.28XML_Formatted_Emails.29|in this link]].
Once you’ve configured the API by Email feature, restart the CommitServer service in order for the changes to take effect.

 
==New Account XML Transaction Sample==
===Editing the XML===
The sample below creates a new account using the data passed to the system in the RecordData section of the XML, with the following details in the account:
#Account Name.
#Contact Name.
#Phone Number.
#Email Address.

More information can be added to the XML by adding more data to the RecordData section of the XML. The XML tags for each CommitCRM Accounts field can be found [[API_Reference_Manual#Account_Fields |in this link]].

The changes to the XMLneed to be made on the following lines:
{| class="wikitable"
|-
! Field
! Description
|-
| '''Line 5'''
| Change youremail@yourdomain.com to the address you want the automated responses sent to.
|-
| '''Line 6'''
| Change the-predefined-api-password to the API password configured in ServerConfig.exe. '''Please Note''' that the XML password feature is optional, and we only recommend using it to avoid unwanted XML transactions from affecting your Database.
|-
| '''Lines 9-14'''
| The web form variables should replace the text within the {} containers
|}

 
===XML Sample===
<nowiki>
<?xml version="1.0" ?>
<?commitcrmxml version = "1.0" ?>
<CommitCRMTransaction>
<ExternalApplicationName>WebsiteSignup</ExternalApplicationName>
<SendResponseToEmail>youremail@yourdomain.com</SendResponseToEmail>
<Password>the-predefined-api-password</Password>
<ReturnTransactionID>data from external application (will be returned as-is in the response)
</ReturnTransactionID>
<DataKind>ACCOUNT</DataKind>
<RecordData>
<FLDCRDCOMPANY>{Web-Form-Account-Name-Here}</FLDCRDCOMPANY>
<FLDCRDCONTACT>{Web-Form-Contacts-First-&-Last-Name-Here}</FLDCRDCONTACT>
<FLDCRDPHONE1>{Web-Form-Phone-Number-Here}</FLDCRDPHONE1>
<FLDCRDEMAIL1>{Web-Form-Email-Address-Here}</FLDCRDEMAIL1>
</RecordData>
</CommitCRMTransaction>
</nowiki>

==Troubleshooting==
Before troubleshooting the Commit Email Connector, we suggest verifying that an email hass been sent from your web form. You can also first test your form by sending the XML emails to your private email account, review it and then forward it to the connector, once all is good, you can update the script to send directly to the Commit Email Connector.

If your XML does not create a new account, please use this following test XML to verify that the Commit Email Connector is receiving emails and processing XML transactions.

To test the Commit Email Connector, please follow these steps:
#Set the API password in ServerConfig.exe to “qwerty”, and restart the CommitServer Service.
#Copy the following Troubleshooting XML to a blank Plain Text email message.
#Replace Your@emailhere.com (in the XML) with your own email address for the log to be sent there.

If the XML creates an account called "XML Test", then this means that the problem is in your XML. To troubleshoot XML syntax errors, please enable XML responses in ServerConfig.exe, and set your XML to respond to an email address you have access to (Line 5 of the XML).

If the account has not been created, a log should be sent to the email address you placed in line 5 of the XML. The log file should say the exact reason the account was not created for you to correct in the XML.

 
===Troubleshooting XML===
<?xml version="1.0" ?>
<?commitcrmxml version = "1.0" ?>
<CommitCRMTransaction>
<ExternalApplicationName>WebsiteSignup</ExternalApplicationName>
<SendResponseToEmail>Your@emailhere.com</SendResponseToEmail>
<Password>qwerty</Password>
<ReturnTransactionID>data from external application (will be returned as-is in the response)
</ReturnTransactionID>
<DataKind>ACCOUNT</DataKind>
<RecordData> <FLDCRDCOMPANY>XML Test</FLDCRDCOMPANY> <FLDCRDCONTACT>Abe Lincoln</FLDCRDCONTACT> <FLDCRDPHONE1>+13235556767</FLDCRDPHONE1> <FLDCRDEMAIL1>Abe@PresidentsClub.com</FLDCRDEMAIL1>
</RecordData>
</CommitCRMTransaction>

 
==See Also==
[[Email_Connector|Commit Email Connector User Manual]] 
[[Email_Connector_FAQ|Commit Email Connector FAQ]] 
[[Category:KB|Accounts]]

KB: Managing Group Email Subscriptions

2010-03-09T18:59:00Z

Reno: /* Unsubscribing Your Customers */

==Introduction==
Sometimes we like to send group emails out to customers regarding promotions, season’s greetings, new services, and new products. Since not all customers are interested in receiving such messages, business go to great lengths to keep records of which customers want to receive which types of email messages.

This article describes how you can use CommitCRM to create your own data tab that manages your email groups; whether a customer is subscribed to that group, and sending out the email to those groups.

__TOC__

 
==Preparing the Database Architecture for Additional Data==
 
===Creating a Tab for Email Groups===
Before we can begin with the customizations, it is best to run a CommitCRM backup process, to make sure that you have a restore point to before you’ve customized the system. Only after the system has been backed up, create the fields that will contain the data about our email groups, we need to [[Field_Customization#Adding_New_Data_Tabs_to_the_Display|create a new tab]] that will house the data fields, while still keeping them separate from the rest of your CommitCRM data.
*We’ll need to create the new tab within the Accounts screen, and call the tab we’re creating Email Groups.
Once we have created the Email Groups tab, we can move on to the next step: Creating Data Fields for Our Email Groups.

[[File:email groups01.jpg|640 px|center]] 

 
=== Creating Data Fields for Our Email Groups===
Once we have a tab that can house the user-defined fields we intend to create in this section, we can go ahead and [[Field_Customization#Creating_New_Data_Fields_to_the_Display|create new data fields]] which need to hold only 2 values each; True and False will be fine, so we’re going to choose to create Yes or No fields (Checkbox Fields).

During the creation of the first field, you’ll need to create a subject group for the tab you’re creating. Field Subject groups allow you to easily group the fields you create so that you can filter your lists by this subject later, in order to be able to select from a dedicated list of these fields. We’ll get in to that later in this article.

#Go into Field Management. (Accounts Menu > Tools > Tab Management)
#Select ‘Add New Fields’ to Tab.
#Create a new Subject Group called ‘Email Groups’, select it and click Next.
#Give your group a name and select ‘Yes or No’ in the Field Type.
#Place your new field where you want to see it in the tab.
#Repeat the creation process for each field you want to create (each field you create represents a group and whether the account is included in this group or not).
##Add the fields you’re creating to the Email Groups Subject that you already made.
#Close the Field Management window in order to save your changes.

[[File:email groups02.jpg|center]] 
[[File:email groups03.jpg|640 px|center]] 

 
==Subscribing Your Accounts to Email Groups==
At this point, you’ve already created an Email Groups tab with checkboxes representing each email group you’re managing. The next step is to subscribe your accounts to relevant by marking fields that they want to be subscribed to. This needs to be done separately for each account; however, you can have this field updated while [[Import_Accounts|importing new accounts]] from external files.

 
==Filtering Your List By These Fields==
Before you can send out the group emails, you need to filter the accounts list according to the group you want to email to, so that the system knows which accounts you want to send the group email message to. Filtering the list is a rather simple task to perform since we’ve added all the fields to the same Field Subject Category (i.e. ‘Email Groups’). Once you’ve filtered your account list to only include the accounts in a specific email group, you can go on to sending the email message.

To filter your list by one of the Email Groups you’re managing, please follow these steps.

#Activate the Advanced Filter option (Mark the Filter checkbox in the blue filter bar in the accounts screen), and open the Filter window.
#Switch to the By Subject Tab.
#Select the Email Groups Subject from the Subject drop down list.
#Select the Group you’d like to filter the list by in the first filter rule line.
#Mark the checkbox in right side of the rule to indicate that you want to filter based on the True value.

[[File:email groups04.jpg|center]] 

 
==Sending the Group Emails to your customers==
Once your accounts list has been filtered to only reflect the accounts that are part of a specific Email Group, you can continue to the next step by preparing the email you intend to send out. Using CommitCRM, you have 2 very powerful options that can send your group email out to your customers. Each method has its benefits, so the best way to choose the correct method is to know what kind of data will need to have merged from the CommitCRM database (if any) into the message.

{| class="wikitable"
|-
! Group Mail Method
! Description
|-
| Internal CommitCRM Group Mail
| This method allows you to create a static email message that can be emailed to the accounts list you’ve filtered, or all your accounts if the list is not filtered. The static message would not include any referenced database information; however, this method is the most quick and convenient way to send out group emails to your customers. This method includes optional fields for the Subject field and Attachments and requires Microsoft® Outlook® to be installed and configured.
For more information see [[KB:_Sending_Group_Emails_to_your_CommitCRM_Accounts|CommitCRM Group Emails]].
|-
|CommitCRM-MSWord Mail Merge
| This method allows you to create a static email template in MS Word, and to have that text populated with CommitCRM referenced account data. This data can be exported from anywhere in the CommitCRM database, and can be easily added to your template so that the message sent to each customer would include the data from the account that the email address came out of. This method is useful if your group email only needs database orientated information embedded in the message.
For more information see [[KB:_Emailing_your_customers_using_Mail_Merge|Commit Mail Merge]].
|}

 
==Unsubscribing Your Customers==
Sometimes customers no longer require some or all of your email newsletters, and need to be removed from the mailing list in the easiest manner; adding a note in the email telling your customer to reply to the email requesting the removal of the subscription by just typing the word '''Unsubscribe'''.

This way you can set up an MS Outlook rule that automatically files the email in a special MS Outlook folder to be processed by an employee manually in CommitCRM.

 
===Automatic Links To Remove A Subscription===
You can offer your customers the option to automatically remove an email group subscription by clicking a link within the email message HTML email. In order for this to work; you would need a Web Server that supports a server side scripting option such as PHP (used in the samples listed below) and the Commit Email Connector.

Preparation for this type of function would involve setting up an XML template that receives the information from the link and automatically emails the xml template to the Commit Email Connector, using a PHP script that we will also create with you. Once the Commit Email Connector receives the XML message; the system will immediately apply the transaction in the XML to the CommitCRM database. In this case; the transaction would be rather simple:
* '''Step 1''': Validate Transaction Authentication, using API Password.
* '''Step 2''': Identify Customer using Customer RECID
* '''Step 3''': Identify Email group to cancel subscription for
* '''Step 4''': Update value to "False".

'''Please note''': this is an advanced option for users with experience with web servers and PHP (or similar) scripting.

 
====Preparation====
The way this is going to work is that the customer clicks a link automatically generated specially for that customer when you send an HTML Email Template. This is done by placing the CommitCRM Account Value (i.e. unique technical identifier) within the link that you're sending (Explained below). Within the link is the URL to the PHP script (explained below), with the Account RECID.

The PHP script needs to take that parameter, and inserts it into a predefined XML template to be emailed to Commit Email Connector; which in turn applies the XML transaction on the CommitCRM database (this is all part of CommitCRM API by Email). Each XML script can only be used on 1 specific email group; so if you use multiple groups, you'll need to create a PHP script and a matching XML for each group.

 
====XML Script====
The sample below changes the value of an email group subscription to "'''False'''"; effectively cancelling the subscription, using only the RECID (Unique Account Identifier) and the email group name.

<pre>
<?xml version="1.0" ?>
<?commitcrmxml version = "1.0" ?>
<CommitCRMTransaction>
<ExternalApplicationName>EmailGroups</ExternalApplicationName>
<SendResponseToEmail>youremail@yourdomain.com</SendResponseToEmail>
<Password>the-predefined-api-password</Password>
<ReturnTransactionID>Removing an Email Subscription
</ReturnTransactionID>
<DataKind>ACCOUNT</DataKind>
<RecordData>
<FLDCRDRECID>{Insert_RECID_HERE}</FLDCRDRECID>
<***********>False</***********>
</RecordData>
</CommitCRMTransaction>
</pre>

Changes to the XML text below need to be made each time the transaction is sent to CommitCRM in order for the database to receive the information in the correct syntax; however, before getting to that, the XML template needs to be created as follows, in order to be hosted on the site and used by a PHP script as an XML processor.

{| class="wikitable"
|-
! Line Number
! Description
|-
| '''5'''
| Replace youremail@yourdomain.com with the email address you want the XML response to. After a successful, or failure, processing of the XML formatted email, Commit Email Connector will send a status update (again in XML textual format) to the specified email address. This can be used for auditing purposes.
|-
| '''6'''
| Replace the-predefined-api-password with your own API password.
Learn more about it [[API_by_Email_and_MSP_Integration#API_by_Email_.28XML_Formatted_Emails.29|here]].
|}

 

====PHP Script====
Using PHP; you'll be able to retrieve the URL parameters, and insert them into the above mentioned XML script automatically; without user interaction. We have included a sample PHP script that can automatically insert the information from the URL directly into the XML template, to be automatically emailed to the CommitCRM Server.

The following script can be used to cancel any email group subscription; since the URL parameters will have all the account and email group identification information required in order to complete the transaction. This means that you can use the following script in order to cancel any email group subscription for your customers.

'''Please Note:''' This script has been tested using PHP5; and may require the same version installed on the web server in order to work.

<pre><nowiki>
<?php
//This script is meant for basic CommitCRM database manipulation. The samples included
//here can be adjusted to include different data in the transaction; more information on
//using XML can be found in this link: http://www.commitcrm.com/wiki/API_Code_Samples#XML_samples.

//================================================================================================
//INSTRUCTIONS: The following variables need to be adjusted in order to make the PHP script know
//how to communicate with Commit Email Connector. The following information will tell the script where
//to send the XML; and how to identify the source address; Please adjust the variables to your own
//preference.

//Edit this variable to reflect the address you want the AI response sent to.
$responsemail = ''response@emailaddress.com';
//Edit this variable to reflect the API Password configured in ServerConfig.exe
$apipasswd = 'your_API_Passwd';
//Edit this variable to reflect the XML Email Destination:
$email_to = ''EmailConnector@yourbusiness.com';
//Edit this variable to reflect the XML Email Subject:
$subject = 'Remove Email Subscription';
//Edit this variable to reflect the XML source email address (Web Form ReplyTo)(Leave "From: " intact):
$replyto = 'From: Webform@emailaddress.com';
//================================================================================================

//Constant variables - These variables will serve to identify the CommitCRM Account and Email Group
//to cancel. Do not edit below this comment!
$recoid = $_GET['recid'];
$emailgroup = $_GET['group'];

//XML Template - Do not alter!
$xml = '<?xml version="1.0" ?>
<?commitcrmxml version = "1.0" ?>
<CommitCRMTransaction>
<ExternalApplicationName>EmailGroups</ExternalApplicationName>
<SendResponseToEmail>' . $responsemail . '</SendResponseToEmail>
<Password>' . $apipasswd . '</Password>
<ReturnTransactionID>Email Group Cancellation</ReturnTransactionID>
<DataKind>ACCOUNT</DataKind>
<RecordData>
<FLDCRDRECID>' . $recoid . '</FLDCRDRECID>
<' . $emailgroup . '>False</' . $emailgroup . '>
</RecordData>
</CommitCRMTransaction>';

//This command will email the XML.
mail($email_to, $subject, $xml, $header);

//This command will give an on screen confirmation to the user.
echo 'Your request has been sent for processing. Thank You.';
?>
</nowiki></pre>

 
====Creating Your Link With CommitCRM Templates====
When you create your newsletter you can use the email template you send from within CommitCRM or MS Word® Mail Merge to create a unique links for each customer that already include the account RECID parameter and the group identifier; so that your customers can easily click the link to trigger the XML to be applied with that accounts RECID.

The 2 variables in the link need to be gathered as follows:
* Group - Right click the email group checkbox field that represents the group you want the link to cancel, and select Field Settings > Advanced > Tech. Rec ID. This value will need to be manually updated in the link
* Recid - Each customer has a Record Identifier that needs to be passed in order for the system to recognize the account that's canceling the subscription. This RECID is available for each account from the Accounts > Notes > Right Click the Record ID button.

When inserting your link into the template; make sure to use the following syntax:
<nowiki>http://www.YourWebServer.com/script.php?group={email_group_Tech_Rec_ID}&recid={Account_Rec_ID}</nowiki>

'''Example: '''
<nowiki>http://127.0.0.1/script.php?group=FLDUSRCRD2Z3U98RAJNY&recid=CRDCO94HUDF8JE06KGTG</nowiki>

If you use [[Email_Templates|Email Templates]] or MS Word® Mail Merge to generate your news letters; then you can have the Account Record Identifier automatically added into each link sent to each customer within the newsletter; here's an example of how to set this in an email template:
<nowiki>http://127.0.0.1/script.php?group=FLDUSRCRD2Z3U98RAJNY&recid=<CMTLBLDATA_FLDCRDRECID></nowiki>

 

==See Also==
*[[Field_Customization#Adding_New_Data_Tabs_to_the_Display|Create a new tab]]
*[[Field_Customization#Creating_New_Data_Fields_to_the_Display|Create new data fields]]
*[[Import_Accounts|Importing new accounts]]
*[[KB:_Sending_Group_Emails_to_your_CommitCRM_Accounts|CommitCRM Group Emails]]
*[[KB:_Emailing_your_customers_using_Mail_Merge|Commit Mail Merge]]
*[[API_Code_Samples#XML_samples|API Code Samples]]
*[[Email_Templates|Email Templates]]
*[[KB:_Emailing_your_customers_using_Mail_Merge|Emailing your customers using Mail Merge]]
*[http://www.php.net/manual/en/index.php PHP5 Manual]
*[http://devzone.zend.com/article/2387 XML and PHP5 Tutorial]

[[Category:KB|Email]]

KB: Managing Group Email Subscriptions

2010-03-09T18:57:34Z

Reno: /* XML Script */

==Introduction==
Sometimes we like to send group emails out to customers regarding promotions, season’s greetings, new services, and new products. Since not all customers are interested in receiving such messages, business go to great lengths to keep records of which customers want to receive which types of email messages.

This article describes how you can use CommitCRM to create your own data tab that manages your email groups; whether a customer is subscribed to that group, and sending out the email to those groups.

__TOC__

 
==Preparing the Database Architecture for Additional Data==
 
===Creating a Tab for Email Groups===
Before we can begin with the customizations, it is best to run a CommitCRM backup process, to make sure that you have a restore point to before you’ve customized the system. Only after the system has been backed up, create the fields that will contain the data about our email groups, we need to [[Field_Customization#Adding_New_Data_Tabs_to_the_Display|create a new tab]] that will house the data fields, while still keeping them separate from the rest of your CommitCRM data.
*We’ll need to create the new tab within the Accounts screen, and call the tab we’re creating Email Groups.
Once we have created the Email Groups tab, we can move on to the next step: Creating Data Fields for Our Email Groups.

[[File:email groups01.jpg|640 px|center]] 

 
=== Creating Data Fields for Our Email Groups===
Once we have a tab that can house the user-defined fields we intend to create in this section, we can go ahead and [[Field_Customization#Creating_New_Data_Fields_to_the_Display|create new data fields]] which need to hold only 2 values each; True and False will be fine, so we’re going to choose to create Yes or No fields (Checkbox Fields).

During the creation of the first field, you’ll need to create a subject group for the tab you’re creating. Field Subject groups allow you to easily group the fields you create so that you can filter your lists by this subject later, in order to be able to select from a dedicated list of these fields. We’ll get in to that later in this article.

#Go into Field Management. (Accounts Menu > Tools > Tab Management)
#Select ‘Add New Fields’ to Tab.
#Create a new Subject Group called ‘Email Groups’, select it and click Next.
#Give your group a name and select ‘Yes or No’ in the Field Type.
#Place your new field where you want to see it in the tab.
#Repeat the creation process for each field you want to create (each field you create represents a group and whether the account is included in this group or not).
##Add the fields you’re creating to the Email Groups Subject that you already made.
#Close the Field Management window in order to save your changes.

[[File:email groups02.jpg|center]] 
[[File:email groups03.jpg|640 px|center]] 

 
==Subscribing Your Accounts to Email Groups==
At this point, you’ve already created an Email Groups tab with checkboxes representing each email group you’re managing. The next step is to subscribe your accounts to relevant by marking fields that they want to be subscribed to. This needs to be done separately for each account; however, you can have this field updated while [[Import_Accounts|importing new accounts]] from external files.

 
==Filtering Your List By These Fields==
Before you can send out the group emails, you need to filter the accounts list according to the group you want to email to, so that the system knows which accounts you want to send the group email message to. Filtering the list is a rather simple task to perform since we’ve added all the fields to the same Field Subject Category (i.e. ‘Email Groups’). Once you’ve filtered your account list to only include the accounts in a specific email group, you can go on to sending the email message.

To filter your list by one of the Email Groups you’re managing, please follow these steps.

#Activate the Advanced Filter option (Mark the Filter checkbox in the blue filter bar in the accounts screen), and open the Filter window.
#Switch to the By Subject Tab.
#Select the Email Groups Subject from the Subject drop down list.
#Select the Group you’d like to filter the list by in the first filter rule line.
#Mark the checkbox in right side of the rule to indicate that you want to filter based on the True value.

[[File:email groups04.jpg|center]] 

 
==Sending the Group Emails to your customers==
Once your accounts list has been filtered to only reflect the accounts that are part of a specific Email Group, you can continue to the next step by preparing the email you intend to send out. Using CommitCRM, you have 2 very powerful options that can send your group email out to your customers. Each method has its benefits, so the best way to choose the correct method is to know what kind of data will need to have merged from the CommitCRM database (if any) into the message.

{| class="wikitable"
|-
! Group Mail Method
! Description
|-
| Internal CommitCRM Group Mail
| This method allows you to create a static email message that can be emailed to the accounts list you’ve filtered, or all your accounts if the list is not filtered. The static message would not include any referenced database information; however, this method is the most quick and convenient way to send out group emails to your customers. This method includes optional fields for the Subject field and Attachments and requires Microsoft® Outlook® to be installed and configured.
For more information see [[KB:_Sending_Group_Emails_to_your_CommitCRM_Accounts|CommitCRM Group Emails]].
|-
|CommitCRM-MSWord Mail Merge
| This method allows you to create a static email template in MS Word, and to have that text populated with CommitCRM referenced account data. This data can be exported from anywhere in the CommitCRM database, and can be easily added to your template so that the message sent to each customer would include the data from the account that the email address came out of. This method is useful if your group email only needs database orientated information embedded in the message.
For more information see [[KB:_Emailing_your_customers_using_Mail_Merge|Commit Mail Merge]].
|}

 
==Unsubscribing Your Customers==
Sometimes customers no longer require some or all of your email newsletters, and need to be removed from the mailing list in the easiest manner; adding a note in the email telling your customer to reply to the email requesting the removal of the subscription by just typing the word Unsubscribe.

This way you can set up an MS Outlook rule that automatically files the email in a special MS Outlook folder to be processed by an employee manually in CommitCRM.

 
===Automatic Links To Remove A Subscription===
You can offer your customers the option to automatically remove an email group subscription by clicking a link within the email message HTML email. In order for this to work; you would need a Web Server that supports a server side scripting option such as PHP (used in the samples listed below) and the Commit Email Connector.

Preparation for this type of function would involve setting up an XML template that receives the information from the link and automatically emails the xml template to the Commit Email Connector, using a PHP script that we will also create with you. Once the Commit Email Connector receives the XML message; the system will immediately apply the transaction in the XML to the CommitCRM database. In this case; the transaction would be rather simple:
* '''Step 1''': Validate Transaction Authentication, using API Password.
* '''Step 2''': Identify Customer using Customer RECID
* '''Step 3''': Identify Email group to cancel subscription for
* '''Step 4''': Update value to "False".

'''Please note''': this is an advanced option for users with experience with web servers and PHP (or similar) scripting.

 
====Preparation====
The way this is going to work is that the customer clicks a link automatically generated specially for that customer when you send an HTML Email Template. This is done by placing the CommitCRM Account Value (i.e. unique technical identifier) within the link that you're sending (Explained below). Within the link is the URL to the PHP script (explained below), with the Account RECID.

The PHP script needs to take that parameter, and inserts it into a predefined XML template to be emailed to Commit Email Connector; which in turn applies the XML transaction on the CommitCRM database (this is all part of CommitCRM API by Email). Each XML script can only be used on 1 specific email group; so if you use multiple groups, you'll need to create a PHP script and a matching XML for each group.

 
====XML Script====
The sample below changes the value of an email group subscription to "'''False'''"; effectively cancelling the subscription, using only the RECID (Unique Account Identifier) and the email group name.

<pre>
<?xml version="1.0" ?>
<?commitcrmxml version = "1.0" ?>
<CommitCRMTransaction>
<ExternalApplicationName>EmailGroups</ExternalApplicationName>
<SendResponseToEmail>youremail@yourdomain.com</SendResponseToEmail>
<Password>the-predefined-api-password</Password>
<ReturnTransactionID>Removing an Email Subscription
</ReturnTransactionID>
<DataKind>ACCOUNT</DataKind>
<RecordData>
<FLDCRDRECID>{Insert_RECID_HERE}</FLDCRDRECID>
<***********>False</***********>
</RecordData>
</CommitCRMTransaction>
</pre>

Changes to the XML text below need to be made each time the transaction is sent to CommitCRM in order for the database to receive the information in the correct syntax; however, before getting to that, the XML template needs to be created as follows, in order to be hosted on the site and used by a PHP script as an XML processor.

{| class="wikitable"
|-
! Line Number
! Description
|-
| '''5'''
| Replace youremail@yourdomain.com with the email address you want the XML response to. After a successful, or failure, processing of the XML formatted email, Commit Email Connector will send a status update (again in XML textual format) to the specified email address. This can be used for auditing purposes.
|-
| '''6'''
| Replace the-predefined-api-password with your own API password.
Learn more about it [[API_by_Email_and_MSP_Integration#API_by_Email_.28XML_Formatted_Emails.29|here]].
|}

 

====PHP Script====
Using PHP; you'll be able to retrieve the URL parameters, and insert them into the above mentioned XML script automatically; without user interaction. We have included a sample PHP script that can automatically insert the information from the URL directly into the XML template, to be automatically emailed to the CommitCRM Server.

The following script can be used to cancel any email group subscription; since the URL parameters will have all the account and email group identification information required in order to complete the transaction. This means that you can use the following script in order to cancel any email group subscription for your customers.

'''Please Note:''' This script has been tested using PHP5; and may require the same version installed on the web server in order to work.

<pre><nowiki>
<?php
//This script is meant for basic CommitCRM database manipulation. The samples included
//here can be adjusted to include different data in the transaction; more information on
//using XML can be found in this link: http://www.commitcrm.com/wiki/API_Code_Samples#XML_samples.

//================================================================================================
//INSTRUCTIONS: The following variables need to be adjusted in order to make the PHP script know
//how to communicate with Commit Email Connector. The following information will tell the script where
//to send the XML; and how to identify the source address; Please adjust the variables to your own
//preference.

//Edit this variable to reflect the address you want the AI response sent to.
$responsemail = ''response@emailaddress.com';
//Edit this variable to reflect the API Password configured in ServerConfig.exe
$apipasswd = 'your_API_Passwd';
//Edit this variable to reflect the XML Email Destination:
$email_to = ''EmailConnector@yourbusiness.com';
//Edit this variable to reflect the XML Email Subject:
$subject = 'Remove Email Subscription';
//Edit this variable to reflect the XML source email address (Web Form ReplyTo)(Leave "From: " intact):
$replyto = 'From: Webform@emailaddress.com';
//================================================================================================

//Constant variables - These variables will serve to identify the CommitCRM Account and Email Group
//to cancel. Do not edit below this comment!
$recoid = $_GET['recid'];
$emailgroup = $_GET['group'];

//XML Template - Do not alter!
$xml = '<?xml version="1.0" ?>
<?commitcrmxml version = "1.0" ?>
<CommitCRMTransaction>
<ExternalApplicationName>EmailGroups</ExternalApplicationName>
<SendResponseToEmail>' . $responsemail . '</SendResponseToEmail>
<Password>' . $apipasswd . '</Password>
<ReturnTransactionID>Email Group Cancellation</ReturnTransactionID>
<DataKind>ACCOUNT</DataKind>
<RecordData>
<FLDCRDRECID>' . $recoid . '</FLDCRDRECID>
<' . $emailgroup . '>False</' . $emailgroup . '>
</RecordData>
</CommitCRMTransaction>';

//This command will email the XML.
mail($email_to, $subject, $xml, $header);

//This command will give an on screen confirmation to the user.
echo 'Your request has been sent for processing. Thank You.';
?>
</nowiki></pre>

 
====Creating Your Link With CommitCRM Templates====
When you create your newsletter you can use the email template you send from within CommitCRM or MS Word® Mail Merge to create a unique links for each customer that already include the account RECID parameter and the group identifier; so that your customers can easily click the link to trigger the XML to be applied with that accounts RECID.

The 2 variables in the link need to be gathered as follows:
* Group - Right click the email group checkbox field that represents the group you want the link to cancel, and select Field Settings > Advanced > Tech. Rec ID. This value will need to be manually updated in the link
* Recid - Each customer has a Record Identifier that needs to be passed in order for the system to recognize the account that's canceling the subscription. This RECID is available for each account from the Accounts > Notes > Right Click the Record ID button.

When inserting your link into the template; make sure to use the following syntax:
<nowiki>http://www.YourWebServer.com/script.php?group={email_group_Tech_Rec_ID}&recid={Account_Rec_ID}</nowiki>

'''Example: '''
<nowiki>http://127.0.0.1/script.php?group=FLDUSRCRD2Z3U98RAJNY&recid=CRDCO94HUDF8JE06KGTG</nowiki>

If you use [[Email_Templates|Email Templates]] or MS Word® Mail Merge to generate your news letters; then you can have the Account Record Identifier automatically added into each link sent to each customer within the newsletter; here's an example of how to set this in an email template:
<nowiki>http://127.0.0.1/script.php?group=FLDUSRCRD2Z3U98RAJNY&recid=<CMTLBLDATA_FLDCRDRECID></nowiki>

 

==See Also==
*[[Field_Customization#Adding_New_Data_Tabs_to_the_Display|Create a new tab]]
*[[Field_Customization#Creating_New_Data_Fields_to_the_Display|Create new data fields]]
*[[Import_Accounts|Importing new accounts]]
*[[KB:_Sending_Group_Emails_to_your_CommitCRM_Accounts|CommitCRM Group Emails]]
*[[KB:_Emailing_your_customers_using_Mail_Merge|Commit Mail Merge]]
*[[API_Code_Samples#XML_samples|API Code Samples]]
*[[Email_Templates|Email Templates]]
*[[KB:_Emailing_your_customers_using_Mail_Merge|Emailing your customers using Mail Merge]]
*[http://www.php.net/manual/en/index.php PHP5 Manual]
*[http://devzone.zend.com/article/2387 XML and PHP5 Tutorial]

[[Category:KB|Email]]

KB: Managing Group Email Subscriptions

2010-03-09T18:56:50Z

Reno: /* Automatic Links To Remove A Subscription */

==Introduction==
Sometimes we like to send group emails out to customers regarding promotions, season’s greetings, new services, and new products. Since not all customers are interested in receiving such messages, business go to great lengths to keep records of which customers want to receive which types of email messages.

This article describes how you can use CommitCRM to create your own data tab that manages your email groups; whether a customer is subscribed to that group, and sending out the email to those groups.

__TOC__

 
==Preparing the Database Architecture for Additional Data==
 
===Creating a Tab for Email Groups===
Before we can begin with the customizations, it is best to run a CommitCRM backup process, to make sure that you have a restore point to before you’ve customized the system. Only after the system has been backed up, create the fields that will contain the data about our email groups, we need to [[Field_Customization#Adding_New_Data_Tabs_to_the_Display|create a new tab]] that will house the data fields, while still keeping them separate from the rest of your CommitCRM data.
*We’ll need to create the new tab within the Accounts screen, and call the tab we’re creating Email Groups.
Once we have created the Email Groups tab, we can move on to the next step: Creating Data Fields for Our Email Groups.

[[File:email groups01.jpg|640 px|center]] 

 
=== Creating Data Fields for Our Email Groups===
Once we have a tab that can house the user-defined fields we intend to create in this section, we can go ahead and [[Field_Customization#Creating_New_Data_Fields_to_the_Display|create new data fields]] which need to hold only 2 values each; True and False will be fine, so we’re going to choose to create Yes or No fields (Checkbox Fields).

During the creation of the first field, you’ll need to create a subject group for the tab you’re creating. Field Subject groups allow you to easily group the fields you create so that you can filter your lists by this subject later, in order to be able to select from a dedicated list of these fields. We’ll get in to that later in this article.

#Go into Field Management. (Accounts Menu > Tools > Tab Management)
#Select ‘Add New Fields’ to Tab.
#Create a new Subject Group called ‘Email Groups’, select it and click Next.
#Give your group a name and select ‘Yes or No’ in the Field Type.
#Place your new field where you want to see it in the tab.
#Repeat the creation process for each field you want to create (each field you create represents a group and whether the account is included in this group or not).
##Add the fields you’re creating to the Email Groups Subject that you already made.
#Close the Field Management window in order to save your changes.

[[File:email groups02.jpg|center]] 
[[File:email groups03.jpg|640 px|center]] 

 
==Subscribing Your Accounts to Email Groups==
At this point, you’ve already created an Email Groups tab with checkboxes representing each email group you’re managing. The next step is to subscribe your accounts to relevant by marking fields that they want to be subscribed to. This needs to be done separately for each account; however, you can have this field updated while [[Import_Accounts|importing new accounts]] from external files.

 
==Filtering Your List By These Fields==
Before you can send out the group emails, you need to filter the accounts list according to the group you want to email to, so that the system knows which accounts you want to send the group email message to. Filtering the list is a rather simple task to perform since we’ve added all the fields to the same Field Subject Category (i.e. ‘Email Groups’). Once you’ve filtered your account list to only include the accounts in a specific email group, you can go on to sending the email message.

To filter your list by one of the Email Groups you’re managing, please follow these steps.

#Activate the Advanced Filter option (Mark the Filter checkbox in the blue filter bar in the accounts screen), and open the Filter window.
#Switch to the By Subject Tab.
#Select the Email Groups Subject from the Subject drop down list.
#Select the Group you’d like to filter the list by in the first filter rule line.
#Mark the checkbox in right side of the rule to indicate that you want to filter based on the True value.

[[File:email groups04.jpg|center]] 

 
==Sending the Group Emails to your customers==
Once your accounts list has been filtered to only reflect the accounts that are part of a specific Email Group, you can continue to the next step by preparing the email you intend to send out. Using CommitCRM, you have 2 very powerful options that can send your group email out to your customers. Each method has its benefits, so the best way to choose the correct method is to know what kind of data will need to have merged from the CommitCRM database (if any) into the message.

{| class="wikitable"
|-
! Group Mail Method
! Description
|-
| Internal CommitCRM Group Mail
| This method allows you to create a static email message that can be emailed to the accounts list you’ve filtered, or all your accounts if the list is not filtered. The static message would not include any referenced database information; however, this method is the most quick and convenient way to send out group emails to your customers. This method includes optional fields for the Subject field and Attachments and requires Microsoft® Outlook® to be installed and configured.
For more information see [[KB:_Sending_Group_Emails_to_your_CommitCRM_Accounts|CommitCRM Group Emails]].
|-
|CommitCRM-MSWord Mail Merge
| This method allows you to create a static email template in MS Word, and to have that text populated with CommitCRM referenced account data. This data can be exported from anywhere in the CommitCRM database, and can be easily added to your template so that the message sent to each customer would include the data from the account that the email address came out of. This method is useful if your group email only needs database orientated information embedded in the message.
For more information see [[KB:_Emailing_your_customers_using_Mail_Merge|Commit Mail Merge]].
|}

 
==Unsubscribing Your Customers==
Sometimes customers no longer require some or all of your email newsletters, and need to be removed from the mailing list in the easiest manner; adding a note in the email telling your customer to reply to the email requesting the removal of the subscription by just typing the word Unsubscribe.

This way you can set up an MS Outlook rule that automatically files the email in a special MS Outlook folder to be processed by an employee manually in CommitCRM.

 
===Automatic Links To Remove A Subscription===
You can offer your customers the option to automatically remove an email group subscription by clicking a link within the email message HTML email. In order for this to work; you would need a Web Server that supports a server side scripting option such as PHP (used in the samples listed below) and the Commit Email Connector.

Preparation for this type of function would involve setting up an XML template that receives the information from the link and automatically emails the xml template to the Commit Email Connector, using a PHP script that we will also create with you. Once the Commit Email Connector receives the XML message; the system will immediately apply the transaction in the XML to the CommitCRM database. In this case; the transaction would be rather simple:
* '''Step 1''': Validate Transaction Authentication, using API Password.
* '''Step 2''': Identify Customer using Customer RECID
* '''Step 3''': Identify Email group to cancel subscription for
* '''Step 4''': Update value to "False".

'''Please note''': this is an advanced option for users with experience with web servers and PHP (or similar) scripting.

 
====Preparation====
The way this is going to work is that the customer clicks a link automatically generated specially for that customer when you send an HTML Email Template. This is done by placing the CommitCRM Account Value (i.e. unique technical identifier) within the link that you're sending (Explained below). Within the link is the URL to the PHP script (explained below), with the Account RECID.

The PHP script needs to take that parameter, and inserts it into a predefined XML template to be emailed to Commit Email Connector; which in turn applies the XML transaction on the CommitCRM database (this is all part of CommitCRM API by Email). Each XML script can only be used on 1 specific email group; so if you use multiple groups, you'll need to create a PHP script and a matching XML for each group.

 
====XML Script====
The sample below changes the value of an email group subscription to "False"; effectively cancelling the subscription, using only the RECID (Unique Account Identifier) and the email group name.

<pre>
<?xml version="1.0" ?>
<?commitcrmxml version = "1.0" ?>
<CommitCRMTransaction>
<ExternalApplicationName>EmailGroups</ExternalApplicationName>
<SendResponseToEmail>youremail@yourdomain.com</SendResponseToEmail>
<Password>the-predefined-api-password</Password>
<ReturnTransactionID>Removing an Email Subscription
</ReturnTransactionID>
<DataKind>ACCOUNT</DataKind>
<RecordData>
<FLDCRDRECID>{Insert_RECID_HERE}</FLDCRDRECID>
<***********>False</***********>
</RecordData>
</CommitCRMTransaction>
</pre>

Changes to the XML text below need to be made each time the transaction is sent to CommitCRM in order for the database to receive the information in the correct syntax; however, before getting to that, the XML template needs to be created as follows, in order to be hosted on the site and used by a PHP script as an XML processor.

{| class="wikitable"
|-
! Line Number
! Description
|-
| '''5'''
| Replace youremail@yourdomain.com with the email address you want the XML response to. After a successful, or failure, processing of the XML formatted email, Commit Email Connector will send a status update (again in XML textual format) to the specified email address. This can be used for auditing purposes.
|-
| '''6'''
| Replace the-predefined-api-password with your own API password.
Learn more about it [[API_by_Email_and_MSP_Integration#API_by_Email_.28XML_Formatted_Emails.29|here]].
|}

 

====PHP Script====
Using PHP; you'll be able to retrieve the URL parameters, and insert them into the above mentioned XML script automatically; without user interaction. We have included a sample PHP script that can automatically insert the information from the URL directly into the XML template, to be automatically emailed to the CommitCRM Server.

The following script can be used to cancel any email group subscription; since the URL parameters will have all the account and email group identification information required in order to complete the transaction. This means that you can use the following script in order to cancel any email group subscription for your customers.

'''Please Note:''' This script has been tested using PHP5; and may require the same version installed on the web server in order to work.

<pre><nowiki>
<?php
//This script is meant for basic CommitCRM database manipulation. The samples included
//here can be adjusted to include different data in the transaction; more information on
//using XML can be found in this link: http://www.commitcrm.com/wiki/API_Code_Samples#XML_samples.

//================================================================================================
//INSTRUCTIONS: The following variables need to be adjusted in order to make the PHP script know
//how to communicate with Commit Email Connector. The following information will tell the script where
//to send the XML; and how to identify the source address; Please adjust the variables to your own
//preference.

//Edit this variable to reflect the address you want the AI response sent to.
$responsemail = ''response@emailaddress.com';
//Edit this variable to reflect the API Password configured in ServerConfig.exe
$apipasswd = 'your_API_Passwd';
//Edit this variable to reflect the XML Email Destination:
$email_to = ''EmailConnector@yourbusiness.com';
//Edit this variable to reflect the XML Email Subject:
$subject = 'Remove Email Subscription';
//Edit this variable to reflect the XML source email address (Web Form ReplyTo)(Leave "From: " intact):
$replyto = 'From: Webform@emailaddress.com';
//================================================================================================

//Constant variables - These variables will serve to identify the CommitCRM Account and Email Group
//to cancel. Do not edit below this comment!
$recoid = $_GET['recid'];
$emailgroup = $_GET['group'];

//XML Template - Do not alter!
$xml = '<?xml version="1.0" ?>
<?commitcrmxml version = "1.0" ?>
<CommitCRMTransaction>
<ExternalApplicationName>EmailGroups</ExternalApplicationName>
<SendResponseToEmail>' . $responsemail . '</SendResponseToEmail>
<Password>' . $apipasswd . '</Password>
<ReturnTransactionID>Email Group Cancellation</ReturnTransactionID>
<DataKind>ACCOUNT</DataKind>
<RecordData>
<FLDCRDRECID>' . $recoid . '</FLDCRDRECID>
<' . $emailgroup . '>False</' . $emailgroup . '>
</RecordData>
</CommitCRMTransaction>';

//This command will email the XML.
mail($email_to, $subject, $xml, $header);

//This command will give an on screen confirmation to the user.
echo 'Your request has been sent for processing. Thank You.';
?>
</nowiki></pre>

 
====Creating Your Link With CommitCRM Templates====
When you create your newsletter you can use the email template you send from within CommitCRM or MS Word® Mail Merge to create a unique links for each customer that already include the account RECID parameter and the group identifier; so that your customers can easily click the link to trigger the XML to be applied with that accounts RECID.

The 2 variables in the link need to be gathered as follows:
* Group - Right click the email group checkbox field that represents the group you want the link to cancel, and select Field Settings > Advanced > Tech. Rec ID. This value will need to be manually updated in the link
* Recid - Each customer has a Record Identifier that needs to be passed in order for the system to recognize the account that's canceling the subscription. This RECID is available for each account from the Accounts > Notes > Right Click the Record ID button.

When inserting your link into the template; make sure to use the following syntax:
<nowiki>http://www.YourWebServer.com/script.php?group={email_group_Tech_Rec_ID}&recid={Account_Rec_ID}</nowiki>

'''Example: '''
<nowiki>http://127.0.0.1/script.php?group=FLDUSRCRD2Z3U98RAJNY&recid=CRDCO94HUDF8JE06KGTG</nowiki>

If you use [[Email_Templates|Email Templates]] or MS Word® Mail Merge to generate your news letters; then you can have the Account Record Identifier automatically added into each link sent to each customer within the newsletter; here's an example of how to set this in an email template:
<nowiki>http://127.0.0.1/script.php?group=FLDUSRCRD2Z3U98RAJNY&recid=<CMTLBLDATA_FLDCRDRECID></nowiki>

 

==See Also==
*[[Field_Customization#Adding_New_Data_Tabs_to_the_Display|Create a new tab]]
*[[Field_Customization#Creating_New_Data_Fields_to_the_Display|Create new data fields]]
*[[Import_Accounts|Importing new accounts]]
*[[KB:_Sending_Group_Emails_to_your_CommitCRM_Accounts|CommitCRM Group Emails]]
*[[KB:_Emailing_your_customers_using_Mail_Merge|Commit Mail Merge]]
*[[API_Code_Samples#XML_samples|API Code Samples]]
*[[Email_Templates|Email Templates]]
*[[KB:_Emailing_your_customers_using_Mail_Merge|Emailing your customers using Mail Merge]]
*[http://www.php.net/manual/en/index.php PHP5 Manual]
*[http://devzone.zend.com/article/2387 XML and PHP5 Tutorial]

[[Category:KB|Email]]

KB: Managing Group Email Subscriptions

2010-03-09T18:56:02Z

Reno: /* Creating Your Link With CommitCRM Templates */

==Introduction==
Sometimes we like to send group emails out to customers regarding promotions, season’s greetings, new services, and new products. Since not all customers are interested in receiving such messages, business go to great lengths to keep records of which customers want to receive which types of email messages.

This article describes how you can use CommitCRM to create your own data tab that manages your email groups; whether a customer is subscribed to that group, and sending out the email to those groups.

__TOC__

 
==Preparing the Database Architecture for Additional Data==
 
===Creating a Tab for Email Groups===
Before we can begin with the customizations, it is best to run a CommitCRM backup process, to make sure that you have a restore point to before you’ve customized the system. Only after the system has been backed up, create the fields that will contain the data about our email groups, we need to [[Field_Customization#Adding_New_Data_Tabs_to_the_Display|create a new tab]] that will house the data fields, while still keeping them separate from the rest of your CommitCRM data.
*We’ll need to create the new tab within the Accounts screen, and call the tab we’re creating Email Groups.
Once we have created the Email Groups tab, we can move on to the next step: Creating Data Fields for Our Email Groups.

[[File:email groups01.jpg|640 px|center]] 

 
=== Creating Data Fields for Our Email Groups===
Once we have a tab that can house the user-defined fields we intend to create in this section, we can go ahead and [[Field_Customization#Creating_New_Data_Fields_to_the_Display|create new data fields]] which need to hold only 2 values each; True and False will be fine, so we’re going to choose to create Yes or No fields (Checkbox Fields).

During the creation of the first field, you’ll need to create a subject group for the tab you’re creating. Field Subject groups allow you to easily group the fields you create so that you can filter your lists by this subject later, in order to be able to select from a dedicated list of these fields. We’ll get in to that later in this article.

#Go into Field Management. (Accounts Menu > Tools > Tab Management)
#Select ‘Add New Fields’ to Tab.
#Create a new Subject Group called ‘Email Groups’, select it and click Next.
#Give your group a name and select ‘Yes or No’ in the Field Type.
#Place your new field where you want to see it in the tab.
#Repeat the creation process for each field you want to create (each field you create represents a group and whether the account is included in this group or not).
##Add the fields you’re creating to the Email Groups Subject that you already made.
#Close the Field Management window in order to save your changes.

[[File:email groups02.jpg|center]] 
[[File:email groups03.jpg|640 px|center]] 

 
==Subscribing Your Accounts to Email Groups==
At this point, you’ve already created an Email Groups tab with checkboxes representing each email group you’re managing. The next step is to subscribe your accounts to relevant by marking fields that they want to be subscribed to. This needs to be done separately for each account; however, you can have this field updated while [[Import_Accounts|importing new accounts]] from external files.

 
==Filtering Your List By These Fields==
Before you can send out the group emails, you need to filter the accounts list according to the group you want to email to, so that the system knows which accounts you want to send the group email message to. Filtering the list is a rather simple task to perform since we’ve added all the fields to the same Field Subject Category (i.e. ‘Email Groups’). Once you’ve filtered your account list to only include the accounts in a specific email group, you can go on to sending the email message.

To filter your list by one of the Email Groups you’re managing, please follow these steps.

#Activate the Advanced Filter option (Mark the Filter checkbox in the blue filter bar in the accounts screen), and open the Filter window.
#Switch to the By Subject Tab.
#Select the Email Groups Subject from the Subject drop down list.
#Select the Group you’d like to filter the list by in the first filter rule line.
#Mark the checkbox in right side of the rule to indicate that you want to filter based on the True value.

[[File:email groups04.jpg|center]] 

 
==Sending the Group Emails to your customers==
Once your accounts list has been filtered to only reflect the accounts that are part of a specific Email Group, you can continue to the next step by preparing the email you intend to send out. Using CommitCRM, you have 2 very powerful options that can send your group email out to your customers. Each method has its benefits, so the best way to choose the correct method is to know what kind of data will need to have merged from the CommitCRM database (if any) into the message.

{| class="wikitable"
|-
! Group Mail Method
! Description
|-
| Internal CommitCRM Group Mail
| This method allows you to create a static email message that can be emailed to the accounts list you’ve filtered, or all your accounts if the list is not filtered. The static message would not include any referenced database information; however, this method is the most quick and convenient way to send out group emails to your customers. This method includes optional fields for the Subject field and Attachments and requires Microsoft® Outlook® to be installed and configured.
For more information see [[KB:_Sending_Group_Emails_to_your_CommitCRM_Accounts|CommitCRM Group Emails]].
|-
|CommitCRM-MSWord Mail Merge
| This method allows you to create a static email template in MS Word, and to have that text populated with CommitCRM referenced account data. This data can be exported from anywhere in the CommitCRM database, and can be easily added to your template so that the message sent to each customer would include the data from the account that the email address came out of. This method is useful if your group email only needs database orientated information embedded in the message.
For more information see [[KB:_Emailing_your_customers_using_Mail_Merge|Commit Mail Merge]].
|}

 
==Unsubscribing Your Customers==
Sometimes customers no longer require some or all of your email newsletters, and need to be removed from the mailing list in the easiest manner; adding a note in the email telling your customer to reply to the email requesting the removal of the subscription by just typing the word Unsubscribe.

This way you can set up an MS Outlook rule that automatically files the email in a special MS Outlook folder to be processed by an employee manually in CommitCRM.

 
===Automatic Links To Remove A Subscription===
You can offer your customers the option to automatically remove an email group subscription by clicking a link within the email message HTML email. In order for this to work; you would need a Web Server that supports a server side scripting option such as PHP (used in the samples listed below) and the Commit Email Connector.

Preparation for this type of function would involve setting up an XML template that receives the information from the link and automatically emails the xml template to the Commit Email Connector, using a PHP script that we will also create with you. Once the Commit Email Connector receives the XML message; the system will immediately apply the transaction in the XML to the CommitCRM database. In this case; the transaction would be rather simple:
* Step 1: Validate Transaction Authentication, using API Password.
* Step 2: Identify Customer using Customer RECID
* Step 3: Identify Email group to cancel subscription for
* Step 4: Update value to "False".

'''Please note''': this is an advanced option for users with experience with web servers and PHP (or similar) scripting.

 
====Preparation====
The way this is going to work is that the customer clicks a link automatically generated specially for that customer when you send an HTML Email Template. This is done by placing the CommitCRM Account Value (i.e. unique technical identifier) within the link that you're sending (Explained below). Within the link is the URL to the PHP script (explained below), with the Account RECID.

The PHP script needs to take that parameter, and inserts it into a predefined XML template to be emailed to Commit Email Connector; which in turn applies the XML transaction on the CommitCRM database (this is all part of CommitCRM API by Email). Each XML script can only be used on 1 specific email group; so if you use multiple groups, you'll need to create a PHP script and a matching XML for each group.

 
====XML Script====
The sample below changes the value of an email group subscription to "False"; effectively cancelling the subscription, using only the RECID (Unique Account Identifier) and the email group name.

<pre>
<?xml version="1.0" ?>
<?commitcrmxml version = "1.0" ?>
<CommitCRMTransaction>
<ExternalApplicationName>EmailGroups</ExternalApplicationName>
<SendResponseToEmail>youremail@yourdomain.com</SendResponseToEmail>
<Password>the-predefined-api-password</Password>
<ReturnTransactionID>Removing an Email Subscription
</ReturnTransactionID>
<DataKind>ACCOUNT</DataKind>
<RecordData>
<FLDCRDRECID>{Insert_RECID_HERE}</FLDCRDRECID>
<***********>False</***********>
</RecordData>
</CommitCRMTransaction>
</pre>

Changes to the XML text below need to be made each time the transaction is sent to CommitCRM in order for the database to receive the information in the correct syntax; however, before getting to that, the XML template needs to be created as follows, in order to be hosted on the site and used by a PHP script as an XML processor.

{| class="wikitable"
|-
! Line Number
! Description
|-
| '''5'''
| Replace youremail@yourdomain.com with the email address you want the XML response to. After a successful, or failure, processing of the XML formatted email, Commit Email Connector will send a status update (again in XML textual format) to the specified email address. This can be used for auditing purposes.
|-
| '''6'''
| Replace the-predefined-api-password with your own API password.
Learn more about it [[API_by_Email_and_MSP_Integration#API_by_Email_.28XML_Formatted_Emails.29|here]].
|}

 

====PHP Script====
Using PHP; you'll be able to retrieve the URL parameters, and insert them into the above mentioned XML script automatically; without user interaction. We have included a sample PHP script that can automatically insert the information from the URL directly into the XML template, to be automatically emailed to the CommitCRM Server.

The following script can be used to cancel any email group subscription; since the URL parameters will have all the account and email group identification information required in order to complete the transaction. This means that you can use the following script in order to cancel any email group subscription for your customers.

'''Please Note:''' This script has been tested using PHP5; and may require the same version installed on the web server in order to work.

<pre><nowiki>
<?php
//This script is meant for basic CommitCRM database manipulation. The samples included
//here can be adjusted to include different data in the transaction; more information on
//using XML can be found in this link: http://www.commitcrm.com/wiki/API_Code_Samples#XML_samples.

//================================================================================================
//INSTRUCTIONS: The following variables need to be adjusted in order to make the PHP script know
//how to communicate with Commit Email Connector. The following information will tell the script where
//to send the XML; and how to identify the source address; Please adjust the variables to your own
//preference.

//Edit this variable to reflect the address you want the AI response sent to.
$responsemail = ''response@emailaddress.com';
//Edit this variable to reflect the API Password configured in ServerConfig.exe
$apipasswd = 'your_API_Passwd';
//Edit this variable to reflect the XML Email Destination:
$email_to = ''EmailConnector@yourbusiness.com';
//Edit this variable to reflect the XML Email Subject:
$subject = 'Remove Email Subscription';
//Edit this variable to reflect the XML source email address (Web Form ReplyTo)(Leave "From: " intact):
$replyto = 'From: Webform@emailaddress.com';
//================================================================================================

//Constant variables - These variables will serve to identify the CommitCRM Account and Email Group
//to cancel. Do not edit below this comment!
$recoid = $_GET['recid'];
$emailgroup = $_GET['group'];

//XML Template - Do not alter!
$xml = '<?xml version="1.0" ?>
<?commitcrmxml version = "1.0" ?>
<CommitCRMTransaction>
<ExternalApplicationName>EmailGroups</ExternalApplicationName>
<SendResponseToEmail>' . $responsemail . '</SendResponseToEmail>
<Password>' . $apipasswd . '</Password>
<ReturnTransactionID>Email Group Cancellation</ReturnTransactionID>
<DataKind>ACCOUNT</DataKind>
<RecordData>
<FLDCRDRECID>' . $recoid . '</FLDCRDRECID>
<' . $emailgroup . '>False</' . $emailgroup . '>
</RecordData>
</CommitCRMTransaction>';

//This command will email the XML.
mail($email_to, $subject, $xml, $header);

//This command will give an on screen confirmation to the user.
echo 'Your request has been sent for processing. Thank You.';
?>
</nowiki></pre>

 
====Creating Your Link With CommitCRM Templates====
When you create your newsletter you can use the email template you send from within CommitCRM or MS Word® Mail Merge to create a unique links for each customer that already include the account RECID parameter and the group identifier; so that your customers can easily click the link to trigger the XML to be applied with that accounts RECID.

The 2 variables in the link need to be gathered as follows:
* Group - Right click the email group checkbox field that represents the group you want the link to cancel, and select Field Settings > Advanced > Tech. Rec ID. This value will need to be manually updated in the link
* Recid - Each customer has a Record Identifier that needs to be passed in order for the system to recognize the account that's canceling the subscription. This RECID is available for each account from the Accounts > Notes > Right Click the Record ID button.

When inserting your link into the template; make sure to use the following syntax:
<nowiki>http://www.YourWebServer.com/script.php?group={email_group_Tech_Rec_ID}&recid={Account_Rec_ID}</nowiki>

'''Example: '''
<nowiki>http://127.0.0.1/script.php?group=FLDUSRCRD2Z3U98RAJNY&recid=CRDCO94HUDF8JE06KGTG</nowiki>

If you use [[Email_Templates|Email Templates]] or MS Word® Mail Merge to generate your news letters; then you can have the Account Record Identifier automatically added into each link sent to each customer within the newsletter; here's an example of how to set this in an email template:
<nowiki>http://127.0.0.1/script.php?group=FLDUSRCRD2Z3U98RAJNY&recid=<CMTLBLDATA_FLDCRDRECID></nowiki>

 

==See Also==
*[[Field_Customization#Adding_New_Data_Tabs_to_the_Display|Create a new tab]]
*[[Field_Customization#Creating_New_Data_Fields_to_the_Display|Create new data fields]]
*[[Import_Accounts|Importing new accounts]]
*[[KB:_Sending_Group_Emails_to_your_CommitCRM_Accounts|CommitCRM Group Emails]]
*[[KB:_Emailing_your_customers_using_Mail_Merge|Commit Mail Merge]]
*[[API_Code_Samples#XML_samples|API Code Samples]]
*[[Email_Templates|Email Templates]]
*[[KB:_Emailing_your_customers_using_Mail_Merge|Emailing your customers using Mail Merge]]
*[http://www.php.net/manual/en/index.php PHP5 Manual]
*[http://devzone.zend.com/article/2387 XML and PHP5 Tutorial]

[[Category:KB|Email]]

KB: Managing Group Email Subscriptions

2010-03-09T18:55:10Z

Reno: /* XML Script */

==Introduction==
Sometimes we like to send group emails out to customers regarding promotions, season’s greetings, new services, and new products. Since not all customers are interested in receiving such messages, business go to great lengths to keep records of which customers want to receive which types of email messages.

This article describes how you can use CommitCRM to create your own data tab that manages your email groups; whether a customer is subscribed to that group, and sending out the email to those groups.

__TOC__

 
==Preparing the Database Architecture for Additional Data==
 
===Creating a Tab for Email Groups===
Before we can begin with the customizations, it is best to run a CommitCRM backup process, to make sure that you have a restore point to before you’ve customized the system. Only after the system has been backed up, create the fields that will contain the data about our email groups, we need to [[Field_Customization#Adding_New_Data_Tabs_to_the_Display|create a new tab]] that will house the data fields, while still keeping them separate from the rest of your CommitCRM data.
*We’ll need to create the new tab within the Accounts screen, and call the tab we’re creating Email Groups.
Once we have created the Email Groups tab, we can move on to the next step: Creating Data Fields for Our Email Groups.

[[File:email groups01.jpg|640 px|center]] 

 
=== Creating Data Fields for Our Email Groups===
Once we have a tab that can house the user-defined fields we intend to create in this section, we can go ahead and [[Field_Customization#Creating_New_Data_Fields_to_the_Display|create new data fields]] which need to hold only 2 values each; True and False will be fine, so we’re going to choose to create Yes or No fields (Checkbox Fields).

During the creation of the first field, you’ll need to create a subject group for the tab you’re creating. Field Subject groups allow you to easily group the fields you create so that you can filter your lists by this subject later, in order to be able to select from a dedicated list of these fields. We’ll get in to that later in this article.

#Go into Field Management. (Accounts Menu > Tools > Tab Management)
#Select ‘Add New Fields’ to Tab.
#Create a new Subject Group called ‘Email Groups’, select it and click Next.
#Give your group a name and select ‘Yes or No’ in the Field Type.
#Place your new field where you want to see it in the tab.
#Repeat the creation process for each field you want to create (each field you create represents a group and whether the account is included in this group or not).
##Add the fields you’re creating to the Email Groups Subject that you already made.
#Close the Field Management window in order to save your changes.

[[File:email groups02.jpg|center]] 
[[File:email groups03.jpg|640 px|center]] 

 
==Subscribing Your Accounts to Email Groups==
At this point, you’ve already created an Email Groups tab with checkboxes representing each email group you’re managing. The next step is to subscribe your accounts to relevant by marking fields that they want to be subscribed to. This needs to be done separately for each account; however, you can have this field updated while [[Import_Accounts|importing new accounts]] from external files.

 
==Filtering Your List By These Fields==
Before you can send out the group emails, you need to filter the accounts list according to the group you want to email to, so that the system knows which accounts you want to send the group email message to. Filtering the list is a rather simple task to perform since we’ve added all the fields to the same Field Subject Category (i.e. ‘Email Groups’). Once you’ve filtered your account list to only include the accounts in a specific email group, you can go on to sending the email message.

To filter your list by one of the Email Groups you’re managing, please follow these steps.

#Activate the Advanced Filter option (Mark the Filter checkbox in the blue filter bar in the accounts screen), and open the Filter window.
#Switch to the By Subject Tab.
#Select the Email Groups Subject from the Subject drop down list.
#Select the Group you’d like to filter the list by in the first filter rule line.
#Mark the checkbox in right side of the rule to indicate that you want to filter based on the True value.

[[File:email groups04.jpg|center]] 

 
==Sending the Group Emails to your customers==
Once your accounts list has been filtered to only reflect the accounts that are part of a specific Email Group, you can continue to the next step by preparing the email you intend to send out. Using CommitCRM, you have 2 very powerful options that can send your group email out to your customers. Each method has its benefits, so the best way to choose the correct method is to know what kind of data will need to have merged from the CommitCRM database (if any) into the message.

{| class="wikitable"
|-
! Group Mail Method
! Description
|-
| Internal CommitCRM Group Mail
| This method allows you to create a static email message that can be emailed to the accounts list you’ve filtered, or all your accounts if the list is not filtered. The static message would not include any referenced database information; however, this method is the most quick and convenient way to send out group emails to your customers. This method includes optional fields for the Subject field and Attachments and requires Microsoft® Outlook® to be installed and configured.
For more information see [[KB:_Sending_Group_Emails_to_your_CommitCRM_Accounts|CommitCRM Group Emails]].
|-
|CommitCRM-MSWord Mail Merge
| This method allows you to create a static email template in MS Word, and to have that text populated with CommitCRM referenced account data. This data can be exported from anywhere in the CommitCRM database, and can be easily added to your template so that the message sent to each customer would include the data from the account that the email address came out of. This method is useful if your group email only needs database orientated information embedded in the message.
For more information see [[KB:_Emailing_your_customers_using_Mail_Merge|Commit Mail Merge]].
|}

 
==Unsubscribing Your Customers==
Sometimes customers no longer require some or all of your email newsletters, and need to be removed from the mailing list in the easiest manner; adding a note in the email telling your customer to reply to the email requesting the removal of the subscription by just typing the word Unsubscribe.

This way you can set up an MS Outlook rule that automatically files the email in a special MS Outlook folder to be processed by an employee manually in CommitCRM.

 
===Automatic Links To Remove A Subscription===
You can offer your customers the option to automatically remove an email group subscription by clicking a link within the email message HTML email. In order for this to work; you would need a Web Server that supports a server side scripting option such as PHP (used in the samples listed below) and the Commit Email Connector.

Preparation for this type of function would involve setting up an XML template that receives the information from the link and automatically emails the xml template to the Commit Email Connector, using a PHP script that we will also create with you. Once the Commit Email Connector receives the XML message; the system will immediately apply the transaction in the XML to the CommitCRM database. In this case; the transaction would be rather simple:
* Step 1: Validate Transaction Authentication, using API Password.
* Step 2: Identify Customer using Customer RECID
* Step 3: Identify Email group to cancel subscription for
* Step 4: Update value to "False".

'''Please note''': this is an advanced option for users with experience with web servers and PHP (or similar) scripting.

 
====Preparation====
The way this is going to work is that the customer clicks a link automatically generated specially for that customer when you send an HTML Email Template. This is done by placing the CommitCRM Account Value (i.e. unique technical identifier) within the link that you're sending (Explained below). Within the link is the URL to the PHP script (explained below), with the Account RECID.

The PHP script needs to take that parameter, and inserts it into a predefined XML template to be emailed to Commit Email Connector; which in turn applies the XML transaction on the CommitCRM database (this is all part of CommitCRM API by Email). Each XML script can only be used on 1 specific email group; so if you use multiple groups, you'll need to create a PHP script and a matching XML for each group.

 
====XML Script====
The sample below changes the value of an email group subscription to "False"; effectively cancelling the subscription, using only the RECID (Unique Account Identifier) and the email group name.

<pre>
<?xml version="1.0" ?>
<?commitcrmxml version = "1.0" ?>
<CommitCRMTransaction>
<ExternalApplicationName>EmailGroups</ExternalApplicationName>
<SendResponseToEmail>youremail@yourdomain.com</SendResponseToEmail>
<Password>the-predefined-api-password</Password>
<ReturnTransactionID>Removing an Email Subscription
</ReturnTransactionID>
<DataKind>ACCOUNT</DataKind>
<RecordData>
<FLDCRDRECID>{Insert_RECID_HERE}</FLDCRDRECID>
<***********>False</***********>
</RecordData>
</CommitCRMTransaction>
</pre>

Changes to the XML text below need to be made each time the transaction is sent to CommitCRM in order for the database to receive the information in the correct syntax; however, before getting to that, the XML template needs to be created as follows, in order to be hosted on the site and used by a PHP script as an XML processor.

{| class="wikitable"
|-
! Line Number
! Description
|-
| '''5'''
| Replace youremail@yourdomain.com with the email address you want the XML response to. After a successful, or failure, processing of the XML formatted email, Commit Email Connector will send a status update (again in XML textual format) to the specified email address. This can be used for auditing purposes.
|-
| '''6'''
| Replace the-predefined-api-password with your own API password.
Learn more about it [[API_by_Email_and_MSP_Integration#API_by_Email_.28XML_Formatted_Emails.29|here]].
|}

 

====PHP Script====
Using PHP; you'll be able to retrieve the URL parameters, and insert them into the above mentioned XML script automatically; without user interaction. We have included a sample PHP script that can automatically insert the information from the URL directly into the XML template, to be automatically emailed to the CommitCRM Server.

The following script can be used to cancel any email group subscription; since the URL parameters will have all the account and email group identification information required in order to complete the transaction. This means that you can use the following script in order to cancel any email group subscription for your customers.

'''Please Note:''' This script has been tested using PHP5; and may require the same version installed on the web server in order to work.

<pre><nowiki>
<?php
//This script is meant for basic CommitCRM database manipulation. The samples included
//here can be adjusted to include different data in the transaction; more information on
//using XML can be found in this link: http://www.commitcrm.com/wiki/API_Code_Samples#XML_samples.

//================================================================================================
//INSTRUCTIONS: The following variables need to be adjusted in order to make the PHP script know
//how to communicate with Commit Email Connector. The following information will tell the script where
//to send the XML; and how to identify the source address; Please adjust the variables to your own
//preference.

//Edit this variable to reflect the address you want the AI response sent to.
$responsemail = ''response@emailaddress.com';
//Edit this variable to reflect the API Password configured in ServerConfig.exe
$apipasswd = 'your_API_Passwd';
//Edit this variable to reflect the XML Email Destination:
$email_to = ''EmailConnector@yourbusiness.com';
//Edit this variable to reflect the XML Email Subject:
$subject = 'Remove Email Subscription';
//Edit this variable to reflect the XML source email address (Web Form ReplyTo)(Leave "From: " intact):
$replyto = 'From: Webform@emailaddress.com';
//================================================================================================

//Constant variables - These variables will serve to identify the CommitCRM Account and Email Group
//to cancel. Do not edit below this comment!
$recoid = $_GET['recid'];
$emailgroup = $_GET['group'];

//XML Template - Do not alter!
$xml = '<?xml version="1.0" ?>
<?commitcrmxml version = "1.0" ?>
<CommitCRMTransaction>
<ExternalApplicationName>EmailGroups</ExternalApplicationName>
<SendResponseToEmail>' . $responsemail . '</SendResponseToEmail>
<Password>' . $apipasswd . '</Password>
<ReturnTransactionID>Email Group Cancellation</ReturnTransactionID>
<DataKind>ACCOUNT</DataKind>
<RecordData>
<FLDCRDRECID>' . $recoid . '</FLDCRDRECID>
<' . $emailgroup . '>False</' . $emailgroup . '>
</RecordData>
</CommitCRMTransaction>';

//This command will email the XML.
mail($email_to, $subject, $xml, $header);

//This command will give an on screen confirmation to the user.
echo 'Your request has been sent for processing. Thank You.';
?>
</nowiki></pre>

 
====Creating Your Link With CommitCRM Templates====
When you create your newsletter you can use the email template you send from within CommitCRM or MS Word® Mail Merge to create a unique links for each customer that already include the account RECID parameter and the group identifier; so that your customers can easily click the link to trigger the XML to be applied with that accounts RECID.

The 2 variables in the link need to be gathered as follows:
* Group - Right click the email group checkbox field that represents the group you want the link to cancel, and select Field Settings > Advanced > Tech. Rec ID. This value will need to be manually updated in the link
* Recid - Each customer has a Record Identifier that needs to be passed in order for the system to recognize the account that's canceling the subscription. This RECID is available for each account from the Accounts > Notes > Right Click the Record ID button.

When inserting your link into the template; make sure to use the following syntax:
http://www.YourWebServer.com/script.php?group={email_group_Tech_Rec_ID}&recid={Account_Rec_ID}

'''Example: '''
http://127.0.0.1/script.php?group=FLDUSRCRD2Z3U98RAJNY&recid=CRDCO94HUDF8JE06KGTG

If you use [[Email_Templates|Email Templates]] or MS Word® Mail Merge to generate your news letters; then you can have the Account Record Identifier automatically added into each link sent to each customer within the newsletter; here's an example of how to set this in an email template:
http://127.0.0.1/script.php?group=FLDUSRCRD2Z3U98RAJNY&recid=<CMTLBLDATA_FLDCRDRECID>

 
==See Also==
*[[Field_Customization#Adding_New_Data_Tabs_to_the_Display|Create a new tab]]
*[[Field_Customization#Creating_New_Data_Fields_to_the_Display|Create new data fields]]
*[[Import_Accounts|Importing new accounts]]
*[[KB:_Sending_Group_Emails_to_your_CommitCRM_Accounts|CommitCRM Group Emails]]
*[[KB:_Emailing_your_customers_using_Mail_Merge|Commit Mail Merge]]
*[[API_Code_Samples#XML_samples|API Code Samples]]
*[[Email_Templates|Email Templates]]
*[[KB:_Emailing_your_customers_using_Mail_Merge|Emailing your customers using Mail Merge]]
*[http://www.php.net/manual/en/index.php PHP5 Manual]
*[http://devzone.zend.com/article/2387 XML and PHP5 Tutorial]

[[Category:KB|Email]]

KB: Managing Group Email Subscriptions

2010-03-09T18:54:13Z

Reno:

==Introduction==
Sometimes we like to send group emails out to customers regarding promotions, season’s greetings, new services, and new products. Since not all customers are interested in receiving such messages, business go to great lengths to keep records of which customers want to receive which types of email messages.

This article describes how you can use CommitCRM to create your own data tab that manages your email groups; whether a customer is subscribed to that group, and sending out the email to those groups.

__TOC__

 
==Preparing the Database Architecture for Additional Data==
 
===Creating a Tab for Email Groups===
Before we can begin with the customizations, it is best to run a CommitCRM backup process, to make sure that you have a restore point to before you’ve customized the system. Only after the system has been backed up, create the fields that will contain the data about our email groups, we need to [[Field_Customization#Adding_New_Data_Tabs_to_the_Display|create a new tab]] that will house the data fields, while still keeping them separate from the rest of your CommitCRM data.
*We’ll need to create the new tab within the Accounts screen, and call the tab we’re creating Email Groups.
Once we have created the Email Groups tab, we can move on to the next step: Creating Data Fields for Our Email Groups.

[[File:email groups01.jpg|640 px|center]] 

 
=== Creating Data Fields for Our Email Groups===
Once we have a tab that can house the user-defined fields we intend to create in this section, we can go ahead and [[Field_Customization#Creating_New_Data_Fields_to_the_Display|create new data fields]] which need to hold only 2 values each; True and False will be fine, so we’re going to choose to create Yes or No fields (Checkbox Fields).

During the creation of the first field, you’ll need to create a subject group for the tab you’re creating. Field Subject groups allow you to easily group the fields you create so that you can filter your lists by this subject later, in order to be able to select from a dedicated list of these fields. We’ll get in to that later in this article.

#Go into Field Management. (Accounts Menu > Tools > Tab Management)
#Select ‘Add New Fields’ to Tab.
#Create a new Subject Group called ‘Email Groups’, select it and click Next.
#Give your group a name and select ‘Yes or No’ in the Field Type.
#Place your new field where you want to see it in the tab.
#Repeat the creation process for each field you want to create (each field you create represents a group and whether the account is included in this group or not).
##Add the fields you’re creating to the Email Groups Subject that you already made.
#Close the Field Management window in order to save your changes.

[[File:email groups02.jpg|center]] 
[[File:email groups03.jpg|640 px|center]] 

 
==Subscribing Your Accounts to Email Groups==
At this point, you’ve already created an Email Groups tab with checkboxes representing each email group you’re managing. The next step is to subscribe your accounts to relevant by marking fields that they want to be subscribed to. This needs to be done separately for each account; however, you can have this field updated while [[Import_Accounts|importing new accounts]] from external files.

 
==Filtering Your List By These Fields==
Before you can send out the group emails, you need to filter the accounts list according to the group you want to email to, so that the system knows which accounts you want to send the group email message to. Filtering the list is a rather simple task to perform since we’ve added all the fields to the same Field Subject Category (i.e. ‘Email Groups’). Once you’ve filtered your account list to only include the accounts in a specific email group, you can go on to sending the email message.

To filter your list by one of the Email Groups you’re managing, please follow these steps.

#Activate the Advanced Filter option (Mark the Filter checkbox in the blue filter bar in the accounts screen), and open the Filter window.
#Switch to the By Subject Tab.
#Select the Email Groups Subject from the Subject drop down list.
#Select the Group you’d like to filter the list by in the first filter rule line.
#Mark the checkbox in right side of the rule to indicate that you want to filter based on the True value.

[[File:email groups04.jpg|center]] 

 
==Sending the Group Emails to your customers==
Once your accounts list has been filtered to only reflect the accounts that are part of a specific Email Group, you can continue to the next step by preparing the email you intend to send out. Using CommitCRM, you have 2 very powerful options that can send your group email out to your customers. Each method has its benefits, so the best way to choose the correct method is to know what kind of data will need to have merged from the CommitCRM database (if any) into the message.

{| class="wikitable"
|-
! Group Mail Method
! Description
|-
| Internal CommitCRM Group Mail
| This method allows you to create a static email message that can be emailed to the accounts list you’ve filtered, or all your accounts if the list is not filtered. The static message would not include any referenced database information; however, this method is the most quick and convenient way to send out group emails to your customers. This method includes optional fields for the Subject field and Attachments and requires Microsoft® Outlook® to be installed and configured.
For more information see [[KB:_Sending_Group_Emails_to_your_CommitCRM_Accounts|CommitCRM Group Emails]].
|-
|CommitCRM-MSWord Mail Merge
| This method allows you to create a static email template in MS Word, and to have that text populated with CommitCRM referenced account data. This data can be exported from anywhere in the CommitCRM database, and can be easily added to your template so that the message sent to each customer would include the data from the account that the email address came out of. This method is useful if your group email only needs database orientated information embedded in the message.
For more information see [[KB:_Emailing_your_customers_using_Mail_Merge|Commit Mail Merge]].
|}

 
==Unsubscribing Your Customers==
Sometimes customers no longer require some or all of your email newsletters, and need to be removed from the mailing list in the easiest manner; adding a note in the email telling your customer to reply to the email requesting the removal of the subscription by just typing the word Unsubscribe.

This way you can set up an MS Outlook rule that automatically files the email in a special MS Outlook folder to be processed by an employee manually in CommitCRM.

 
===Automatic Links To Remove A Subscription===
You can offer your customers the option to automatically remove an email group subscription by clicking a link within the email message HTML email. In order for this to work; you would need a Web Server that supports a server side scripting option such as PHP (used in the samples listed below) and the Commit Email Connector.

Preparation for this type of function would involve setting up an XML template that receives the information from the link and automatically emails the xml template to the Commit Email Connector, using a PHP script that we will also create with you. Once the Commit Email Connector receives the XML message; the system will immediately apply the transaction in the XML to the CommitCRM database. In this case; the transaction would be rather simple:
* Step 1: Validate Transaction Authentication, using API Password.
* Step 2: Identify Customer using Customer RECID
* Step 3: Identify Email group to cancel subscription for
* Step 4: Update value to "False".

'''Please note''': this is an advanced option for users with experience with web servers and PHP (or similar) scripting.

 
====Preparation====
The way this is going to work is that the customer clicks a link automatically generated specially for that customer when you send an HTML Email Template. This is done by placing the CommitCRM Account Value (i.e. unique technical identifier) within the link that you're sending (Explained below). Within the link is the URL to the PHP script (explained below), with the Account RECID.

The PHP script needs to take that parameter, and inserts it into a predefined XML template to be emailed to Commit Email Connector; which in turn applies the XML transaction on the CommitCRM database (this is all part of CommitCRM API by Email). Each XML script can only be used on 1 specific email group; so if you use multiple groups, you'll need to create a PHP script and a matching XML for each group.

 
====XML Script====
The sample below changes the value of an email group subscription to "False"; effectively cancelling the subscription, using only the RECID (Unique Account Identifier) and the email group name.

<pre>
<?xml version="1.0" ?>
<?commitcrmxml version = "1.0" ?>
<CommitCRMTransaction>
<ExternalApplicationName>EmailGroups</ExternalApplicationName>
<SendResponseToEmail>youremail@yourdomain.com</SendResponseToEmail>
<Password>the-predefined-api-password</Password>
<ReturnTransactionID>Removing an Email Subscription
</ReturnTransactionID>
<DataKind>ACCOUNT</DataKind>
<RecordData>
<FLDCRDRECID>{Insert_RECID_HERE}</FLDCRDRECID>
<***********>False</***********>
</RecordData>
</CommitCRMTransaction>
</pre>

Changes to the XML text below need to be made each time the transaction is sent to CommitCRM in order for the database to receive the information in the correct syntax; however, before getting to that, the XML template needs to be created as follows, in order to be hosted on the site and used by a PHP script as an XML processor.

{| class="wikitable"
|-
! Line Number
! Description
|-
| '''5'''
| Replace youremail@yourdomain.com with the email address you want the XML response to. After a successful, or failure, processing of the XML formatted email, Commit Email Connector will send a status update (again in XML textual format) to the specified email address. This can be used for auditing purposes.
|-
| '''6'''
| Replace the-predefined-api-password with your own API password.
Learn more about it [[ API_by_Email_and_MSP_Integration#API_by_Email_.28XML_Formatted_Emails.29here]].
|}

 
====PHP Script====
Using PHP; you'll be able to retrieve the URL parameters, and insert them into the above mentioned XML script automatically; without user interaction. We have included a sample PHP script that can automatically insert the information from the URL directly into the XML template, to be automatically emailed to the CommitCRM Server.

The following script can be used to cancel any email group subscription; since the URL parameters will have all the account and email group identification information required in order to complete the transaction. This means that you can use the following script in order to cancel any email group subscription for your customers.

'''Please Note:''' This script has been tested using PHP5; and may require the same version installed on the web server in order to work.

<pre><nowiki>
<?php
//This script is meant for basic CommitCRM database manipulation. The samples included
//here can be adjusted to include different data in the transaction; more information on
//using XML can be found in this link: http://www.commitcrm.com/wiki/API_Code_Samples#XML_samples.

//================================================================================================
//INSTRUCTIONS: The following variables need to be adjusted in order to make the PHP script know
//how to communicate with Commit Email Connector. The following information will tell the script where
//to send the XML; and how to identify the source address; Please adjust the variables to your own
//preference.

//Edit this variable to reflect the address you want the AI response sent to.
$responsemail = ''response@emailaddress.com';
//Edit this variable to reflect the API Password configured in ServerConfig.exe
$apipasswd = 'your_API_Passwd';
//Edit this variable to reflect the XML Email Destination:
$email_to = ''EmailConnector@yourbusiness.com';
//Edit this variable to reflect the XML Email Subject:
$subject = 'Remove Email Subscription';
//Edit this variable to reflect the XML source email address (Web Form ReplyTo)(Leave "From: " intact):
$replyto = 'From: Webform@emailaddress.com';
//================================================================================================

//Constant variables - These variables will serve to identify the CommitCRM Account and Email Group
//to cancel. Do not edit below this comment!
$recoid = $_GET['recid'];
$emailgroup = $_GET['group'];

//XML Template - Do not alter!
$xml = '<?xml version="1.0" ?>
<?commitcrmxml version = "1.0" ?>
<CommitCRMTransaction>
<ExternalApplicationName>EmailGroups</ExternalApplicationName>
<SendResponseToEmail>' . $responsemail . '</SendResponseToEmail>
<Password>' . $apipasswd . '</Password>
<ReturnTransactionID>Email Group Cancellation</ReturnTransactionID>
<DataKind>ACCOUNT</DataKind>
<RecordData>
<FLDCRDRECID>' . $recoid . '</FLDCRDRECID>
<' . $emailgroup . '>False</' . $emailgroup . '>
</RecordData>
</CommitCRMTransaction>';

//This command will email the XML.
mail($email_to, $subject, $xml, $header);

//This command will give an on screen confirmation to the user.
echo 'Your request has been sent for processing. Thank You.';
?>
</nowiki></pre>

 
====Creating Your Link With CommitCRM Templates====
When you create your newsletter you can use the email template you send from within CommitCRM or MS Word® Mail Merge to create a unique links for each customer that already include the account RECID parameter and the group identifier; so that your customers can easily click the link to trigger the XML to be applied with that accounts RECID.

The 2 variables in the link need to be gathered as follows:
* Group - Right click the email group checkbox field that represents the group you want the link to cancel, and select Field Settings > Advanced > Tech. Rec ID. This value will need to be manually updated in the link
* Recid - Each customer has a Record Identifier that needs to be passed in order for the system to recognize the account that's canceling the subscription. This RECID is available for each account from the Accounts > Notes > Right Click the Record ID button.

When inserting your link into the template; make sure to use the following syntax:
http://www.YourWebServer.com/script.php?group={email_group_Tech_Rec_ID}&recid={Account_Rec_ID}

'''Example: '''
http://127.0.0.1/script.php?group=FLDUSRCRD2Z3U98RAJNY&recid=CRDCO94HUDF8JE06KGTG

If you use [[Email_Templates|Email Templates]] or MS Word® Mail Merge to generate your news letters; then you can have the Account Record Identifier automatically added into each link sent to each customer within the newsletter; here's an example of how to set this in an email template:
http://127.0.0.1/script.php?group=FLDUSRCRD2Z3U98RAJNY&recid=<CMTLBLDATA_FLDCRDRECID>

 
==See Also==
*[[Field_Customization#Adding_New_Data_Tabs_to_the_Display|Create a new tab]]
*[[Field_Customization#Creating_New_Data_Fields_to_the_Display|Create new data fields]]
*[[Import_Accounts|Importing new accounts]]
*[[KB:_Sending_Group_Emails_to_your_CommitCRM_Accounts|CommitCRM Group Emails]]
*[[KB:_Emailing_your_customers_using_Mail_Merge|Commit Mail Merge]]
*[[API_Code_Samples#XML_samples|API Code Samples]]
*[[Email_Templates|Email Templates]]
*[[KB:_Emailing_your_customers_using_Mail_Merge|Emailing your customers using Mail Merge]]
*[http://www.php.net/manual/en/index.php PHP5 Manual]
*[http://devzone.zend.com/article/2387 XML and PHP5 Tutorial]

[[Category:KB|Email]]

Online Services

2010-02-25T16:55:50Z

Reno: /* Displaying Products Warranties Online */

{{integration}}

Commit's '''Online Services''' is a powerful feature which allows you to link to web sites (URL) and activate the web application using parameters taken from CommitCRM.

You can define as many online Services as you wish. This feature is available for the following entities: Accounts, Tickets, Assets, Items, Contracts, Knowledge Base Articles and Opportunities.
*Accounts window
*Tickets window
*Dispatcher window
*Asset window
*Items window
*Contracts window
*Opportunities window

==What can I use Online Services for?==
Wouldn't you like your technicians to be able to find an address for a scheduled visit with just a single click? You can do this by defining an Online Service which will open maps site (e.g. Google Maps, Yahoo! Maps etc.) and the map will open automatically on the address of the Account or Contact stored in CommitCRM.

This powerful tool allows you to define any URL and open it with parameters. You can basically do with it whatever you want.

==Adding new Online Services==
To define a new Online Service, Open the Online Services Management window from Settings > Online Services. or click the Online Services icon from the Accounts window toolbar. Click the New button to add a new Online Service and enter the following parameters:

*'''Name''' - The name of the service which will be displayed in the Online Services list and menus throughout the system, for example, "Google Maps".
*'''Base URL''' - The URL you wish to open in order to use the Service. This is the address of the main service (before passing any parameters to it), for example http://maps.google.com/maps.
*'''URL Parameters''' - Parameters which will be appended to the URL in order to create specific queries when opening the URL. These parameters can be CommitCRM Account database fields which will be taken and filled from CommitCRM when clicking the Online Service.

See the Tips and Tricks for examples of useful Online Services

==Activating Online Services==
Online Services can be activated from various places in CommitCRM including:
*The '''Account, Ticket, Asset, Item, Opportunity, Contract, Knowledge Base Article windows''' - click the Online Services icon to activate the service for the selected account
*The '''Dispatcher Windows''' - right-click on a selected Ticket to run any Online Service for the Ticket's Account or Contact (such as displaying a map).
*The '''Calendar / Scheduled Appointments''' views - right-click above an Appointment and select Online Services.
*The '''secondary Contacts tab''' - select a Contact, right-click and select Online Services
*'''Selection field''' - anywhere where the entity selection field is displayed - right-click and select Online Services, activate Online Services.
*'''Secondary Contact selection''' field - right-click and select Online Services.
*The '''Relations tab under Account''' - right-click and select Online Services.

==Possible Usage==
*'''Online Services and Assets''' – Access your MSP product online and pass the Asset ID to display its details from your external system
*'''Online Services and Items''' – Search for better prices for items by passing specific item information directly from within CommitCRM.
*'''Online Services for Assets''' – Search for a specific product review by its hardware serial number.
*'''Online Services for Tickets''' – Search in online knowledge bases for solutions based on the ticket description
*'''Selection field''' - anywhere where the entity selection field is displayed - right-click and select Online Services, activate Online Services.

==Using Lookup Fields==
Lookup Fields can be used in order to pass parameters from an entity which is linked to the entity you are currently using. For example, you can create an Online Service for a Ticket, and pass the address of the account which is linked to the ticket.

This way you can define an Online Service for the Ticket, which will be activated from the Ticket window and will be using Account information.

Lookup Field syntax:

<CMTLBLDATA_FLDTKTCARDID_FLDCRDADDRESS1>

Where:
CMTLBLDATA_FLDTKTCARDID is the pointer to the linked account
FLDCRDADDRESS1 is the account's Address field

==Tips & Tricks (Samples)==
Following are examples of possible Online Services configurations.
These examples are intended to explain the use of Online Services only.

Disclaimer - Before defining your Online Services you should read the terms of use for each web site you want to access. The examples below are displayed to explain how to use online services and how to pass parameters.

===Dialing via Skype===
Requires a '''Telephone Number (E.g. 0012125551234)''' or '''Skype Username''' in the '''Accounts>General>Phone1/2''' field. 
Please create separate services each phone number field.
{| class="wikitable"
|-
! Parameters
! Values
|-
| Name
| Dial Via Skype
|-
| Base URL
| <nowiki>callto://</nowiki>
|-
| URL Parameters
| <CMTLBLDATA_FLDCRDPHONE1>
|-
|
|<CMTLBLDATA_FLDCRDPHONE2>
|}

===Online Account Research===
These services research your Customers information & maps, by referencing different fields that you enter in the database.

====Displaying Address by Domain====
Requires a '''WebAddress''' in the '''Accounts>Details>Web''' field
{| class="wikitable"
|-
! Parameters
! Values
|-
| Name
| Get address from Customer Domain
|-
| Base URL
| <nowiki>http://api.hostip.info/get_html.php</nowiki>
|-
| URL Parameters
| ?ip=<CMTLBLDATA_FLDCRDURL1>&position=true
|}

====Displaying Online Maps====
'''Google Maps''' - Opens Google Maps and displays the Account/Contact address.
{| class="wikitable"
|-
! Parameters
! Values
|-
| Name
| Google Maps
|-
| Base URL
| <nowiki>http://maps.google.com/maps</nowiki>
|-
| URL Parameters
| ?f=q&hl=en&q=<CMTLBLDATA_FLDCRDADDRESS1>+<CMTLBLDATA_FLDCRDCITY>+<CMTLBLDATA_FLDCRDSTATE>+<CMTLBLDATA_FLDCRDZIP>
|}

'''MapQuest''' - Opens MapQuest Map and displays the Account/Contact address.
{| class="wikitable"
|-
! Parameters
! Values
|-
| Name
| MapQuest
|-
| Base URL
| <nowiki>http://www.mapquest.com/maps</nowiki>
|-
| URL Parameters
| /map.adp?searchtype=address&country=<CMTLBLDATA_FLDCRDCOUNTRY>&addtohistory=&searchtab=home&formtype=address&popflag=0&latitude=&longitude=&name=&phone=&level=&cat=&address=&city=<CMTLBLDATA_FLDCRDCITY>&state=<CMTLBLDATA_FLDCRDSTATE>&zipcode=<CMTLBLDATA_FLDCRDZIP>
|}

'''Yahoo! Maps''' - Opens Yahoo! Map and displays the Account/Contact address.
{| class="wikitable"
|-
! Parameters
! Values
|-
| Name
| Yahoo! Maps
|-
| Base URL
| <nowiki>http://maps.yahoo.com</nowiki>
|-
| URL Parameters
| /maps_result?addr=<CMTLBLDATA_FLDCRDADDRESS1>&csz=<CMTLBLDATA_FLDCRDCITY>+<CMTLBLDATA_FLDCRDCOUNTRY>&country=<CMTLBLDATA_FLDCRDSTATE>
|}

'''Geo IP Locator''' - Locates IP addresses on a map (Usually shows location of the ISP)
This service requires a WebAddress in the '''Accounts>Details>Web''' field.
{| class="wikitable"
|-
! Parameters
! Values
|-
| Name
| Geo IP Locator
|-
| Base URL
| <nowiki>http://www.geoiptool.com/en/</nowiki>
|-
| URL Parameters
| ?IP=<CMTLBLDATA_FLDCRDURL1>
|}

====Finding Account Information====
'''Google Company''' - Opens Google and searches for the Account Company Name.

{| class="wikitable"
|-
! Parameters
! Values
|-
| Name
| Google Company
|-
| Base URL
| <nowiki>http://www.google.com/search</nowiki>
|-
| URL Parameters
| ?q=<CMTLBLDATA_FLDCRDCOMPANY>
|}

'''Google Contact''' - Opens Google and searches for the Contact Name.
{| class="wikitable"
|-
! Parameters
! Values
|-
| Name
| Google Contact
|-
| Base URL
| <nowiki>http://www.google.com/search</nowiki>
|-
| URL Parameters
| ?q=<CMTLBLDATA_FLDCRDCONTACT>
|}

'''Validate Email''' - Runs silent queries to check if an email address exists.
{| class="wikitable"
|-
! Parameters
! Values
|-
| Name
| Validate Email
|-
| Base URL
| <nowiki>http://network-tools.com/default.asp</nowiki>
|-
| URL Parameters
| ?prog=validate&host=<CMTLBLDATA_FLDCRDEMAIL1>
|} 

====Displaying Domain WHOIS====

'''Network Solutions Domain WHOIS''' - WHOIS domain registration information by Network Solutions.

Note: Domain must be stripped from URL (without <nowiki>http://</nowiki>).

'''Contributed by DavidW'''
{| class="wikitable"
|-
! Parameters
! Values
|-
| Data Source
| Accounts
|-
| Name
| Domain WHOIS (NetworkSolutions)
|-
| Base URL
| <nowiki>http://www.networksolutions.com/whois-search/</nowiki>
|-
| URL Parameters
| <CMTLBLDATA_FLDCRDURL1>
|}

'''Domain Tools Domain WHOIS''' - WHOIS domain registration information by Domain Tools.

Note: Domain must be stripped from URL (without <nowiki>http://</nowiki>).

'''Contributed by ajgyomber'''
{| class="wikitable"
|-
! Parameters
! Values
|-
| Data Source
| Accounts
|-
| Name
| Domain WHOIS (DomainTools)
|-
| Base URL
| <nowiki>http://whois.domaintools.com/</nowiki>
|-
| URL Parameters
| <CMTLBLDATA_FLDCRDURL1>
|}

'''DNSstuff Domain WHOIS''' - WHOIS domain registration information by DNSstuff.

Note: Domain must be stripped from URL (without <nowiki>http://</nowiki>).

{| class="wikitable"
|-
! Parameters
! Values
|-
| Data Source
| Accounts
|-
| Name
| Domain WHOIS (DNSstuff)
|-
| Base URL
| <nowiki>http://www.dnsstuff.com/dnslite/?r=u2r&domain=</nowiki>
|-
| URL Parameters
| <CMTLBLDATA_FLDCRDURL1>
|}

'''Simple Domain Lookup''' - Displays Country, State, and Domain Alias
This service requires a WebAddress in the '''Accounts>Details>Web''' field.

{| class="wikitable"
|-
! Parameters
! Values
|-
| Data Source
| Accounts
|-
| Name
| Simple Domain Lookup
|-
| Base URL
| <nowiki>http://network-tools.com/default.asp</nowiki>
|-
| URL Parameters
| ?prog=lookup&host=<CMTLBLDATA_FLDCRDURL1>
|}

===Network Diagnostics===
These tools are mostly accessable from the command line in any Linux system, but we thought that it'd be useful to be able to run these tests for your customers, all from the Online Services menu in CommitCRM.

====Network Testing Tools====
'''Ping''' - Performs an automatic ping to your customer web address from a remote server. 
This service requires a WebAddress in the '''Accounts>Details>Web''' field.
{| class="wikitable"
|-
! Parameters
! Values
|-
| Name
| Ping
|-
| Base URL
| <nowiki>http://network-tools.com/default.asp
</nowiki>
|-
| URL Parameters
| ?prog=ping&host=<CMTLBLDATA_FLDCRDURL1>
|} 

'''Trace Route''' - Performs an IP TraceRoute process to your customers website. 
This service requires a WebAddress in the '''Accounts>Details>Web''' field.
{| class="wikitable"
|-
! Parameters
! Values
|-
| Name
| Trace Route
|-
| Base URL
| <nowiki>http://network-tools.com/default.asp
</nowiki>
|-
| URL Parameters
| ?prog=trace&host=<CMTLBLDATA_FLDCRDURL1>
|} 

'''WebSite Up/Down?''' - Checks if your customer website is operational. 
This service requires a WebAddress in the '''Accounts>Details>Web''' field.
{| class="wikitable"
|-
! Parameters
! Values
|-
| Name
| Trace Route
|-
| Base URL
| <nowiki>http://www.downforeveryoneorjustme.com/</nowiki>
|-
| URL Parameters
| <CMTLBLDATA_FLDCRDURL1>
|} 

====DNS WWW & MailServer Record Retrieval====
'''DNS Record Retrieval''' - Displays DNS routing & licensing information based on a domain. 
This service requires a WebAddress in the '''Accounts>Details>Web''' field.
{| class="wikitable"
|-
! Parameters
! Values
|-
| Name
| DNS Record Retrieval
|-
| Base URL
| <nowiki>http://network-tools.com/default.asp
</nowiki>
|-
| URL Parameters
| ?prog=dnsrec&host=<CMTLBLDATA_FLDCRDURL1>
|} 

'''Domain DNS WWW MailSVR Query''' - Displays Verbose Domain based Info 
This service requires a WebAddress in the '''Accounts>Details>Web''' field.
{| class="wikitable"
|-
! Parameters
! Values
|-
| Name
| Domain DNS WWW MailSVR Query
|-
| Base URL
| <nowiki>http://www.checkdns.net/quickcheck.aspx</nowiki>
|-
| URL Parameters
| ?domain=<CMTLBLDATA_FLDCRDURL1>&detailed=1
|} 

'''WebServer Info''' - Displays version & flavor info on your customer website. 
This service requires a WebAddress in the '''Accounts>Details>Web''' field.
{| class="wikitable"
|-
! Parameters
! Values
|-
| Name
| WebServer Info
|-
| Base URL
| <nowiki>http://network-tools.com/default.asp</nowiki>
|-
| URL Parameters
| ?prog=httphead&host=<CMTLBLDATA_FLDCRDURL1>
|} 

'''Domain Express Sumary''' - shows simple location and alias info for an IP address. 
This service requires a WebAddress in the '''Accounts>Details>Web''' field.
{| class="wikitable"
|-
! Parameters
! Values
|-
| Name
| Domain Express Summary
|-
| Base URL
| <nowiki>http://network-tools.com/default.asp</nowiki>
|-
| URL Parameters
| ?prog=express&host=<CMTLBLDATA_FLDCRDURL1>
|} 

'''Email IP Blacklist''' - Queries main spam monitoring servers to see if the IP has been blacklisted. 
This service requires a WebAddress in the '''Accounts>Details>Web''' field.
{| class="wikitable"
|-
! Parameters
! Values
|-
| Name
| Email IP Blacklist
|-
| Base URL
| <nowiki>http://network-tools.com/default.asp</nowiki>
|-
| URL Parameters
| ?prog=sbl&host=<CMTLBLDATA_FLDCRDURL1>
|} 

===Ticket Research===
These Online Services et data from the internet, and show you the results from that process. these services need to be created for the '''Tickets''' screen.

====Finding Ticket Description in Google====
'''Google Ticket''' - Opens Google and searches for the Ticket description. 
{| class="wikitable"
|-
! Parameters
! Values
|-
| Name
| Google Search for Ticket Description
|-
| Base URL
| <nowiki>http://www.google.com/search</nowiki>
|-
| URL Parameters
| ?q=<CMTLBLDATA_FLDTKTPROBLEM>
|}

====Advanced Ticket Reference====
'''EventID.Net Reference''' - References an Windows Alert Event ID number. 
This Service needs the '''Event Source''' copied into the ticket description field, and the '''Event ID number''' in '''Details > Cause'''
{| class="wikitable"
|-
! Parameters
! Values
|-
| Name
| EventID.Net Reference
|-
| Base URL
| <nowiki>http://www.eventid.net/display.asp</nowiki>
|-
| URL Parameters
| ?eventid=<CMTLBLDATA_FLDTKTCAUSE>&source=<CMTLBLDATA_FLDTKTPROBLEM>
|}

'''TechNet Reference''' - References an error with Micorsoft Technet. 
This Service searches TechNet for the '''ticket description'''.
{| class="wikitable"
|-
! Parameters
! Values
|-
| Name
| Technet Reference
|-
| Base URL
| <nowiki>http://social.technet.microsoft.com/Search/en-US</nowiki>
|-
| URL Parameters
| ?query=<CMTLBLDATA_FLDTKTPROBLEM>&ac=8
|}

====Finding Account Address From Ticket (using [[Commit Online Services#Using Lookup Fields|Lookup Field]]) ====
'''Google Address From Ticket''' - Opens Google and searches for the Address of the Account which is linked to the Ticket.
{| class="wikitable"
|-
! Parameters
! Values
|-
| Name
| Google Search for Ticket's Account Address
|-
| Base URL
| <nowiki>http://maps.google.com/maps</nowiki>
|-
| URL Parameters
| ?f=q&hl=en&q=<CMTLBLDATA_FLDTKTCARDID_FLDCRDADDRESS1>+<CMTLBLDATA_FLDTKTCARDID_FLDCRDCITY>+<CMTLBLDATA_FLDTKTCARDID_FLDCRDSTATE>+<CMTLBLDATA_FLDTKTCARDID_FLDCRDZIP>
|}

===Displaying Products Warranties Online===
'''IBM/Lenovo Warranty Lookup''' - Displays IBM/Lenovo products warranty expiration dates, using the products '''Type Number (in Assets > Details > Field2)''' and '''Serial Number (in Assets > Details > Field5)'''.

{| class="wikitable"
|-
! Parameters
! Values
|-
| Data Source
| Assets
|-
| Name
| IBM/Lenovo Warranty Lookup
|-
| Base URL
| <nowiki>http://www-307.ibm.com/pc/support/site.wss/warrantyLookup.do</nowiki>
|-
| URL Parameters
| ?type=<CMTLBLDATA_FLDASTUSER2>&serial=<CMTLBLDATA_FLDASTUSER5>&country=897&iws=off&sitestyle=Lenovo
|}

'''HP Warranty Lookup''' - Displays HP products warranty expiration dates, using the products number and the products serial number.

Note: Product Number goes into Plate# field (<CMTLBLDATA_FLDASTUSER1>).

'''Contributed by Easy I.T'''
{| class="wikitable"
|-
! Parameters
! Values
|-
| Data Source
| Assets
|-
| Name
| HP Warranty Lookup
|-
| Base URL
| <nowiki>http://h20000.www2.hp.com/bizsupport/TechSupport/WarrantyResults.jsp?</nowiki>
|-
| URL Parameters
| lang=en&cc=us&prodSeriesId=454811&prodTypeId=12454&sn=<CMTLBLDATA_FLDASTSERIALNO>&pn=<CMTLBLDATA_FLDASTUSER1>&country=US&nickname=&find=Display+Warranty+Information+%C2%BB
|}

'''DELL Service Contracts and Warranties''' - Displays Dell products warranty expiration dates, using the service tag number.

Note: Customize a Field for Service Tag or use existing field. In this sample we will use Field3 as custumized Service Tag Field

'''Contributed by JoshuaB'''
{| class="wikitable"
|-
! Parameters
! Values
|-
| Data Source
| Assets
|-
| Name
| Dell Warranty Check
|-
| Base URL
| <nowiki>http://support.dell.com/support/topics/global.aspx/support/my_systems_info/details</nowiki>
|-
| URL Parameters
| ?c=us&l=en&s=gen&servicetag=<CMTLBLDATA_FLDASTUSER3>
|}

===Displaying Online Work Orders Status===
'''Work Orders Status Check''' - Track your orders statuses in <nowiki>onforce.com</nowiki>

Note: Set Field1 to order number or change the parameter (<CMTLBLDATA_FLDTKTUSER1>) to a different field.

'''Contributed by secion8'''
{| class="wikitable"
|-
! Parameters
! Values
|-
| Data Source
| Tickets
|-
| Name
| Work Orders Status (onforce.com)
|-
| Base URL
| <nowiki>http://www.onforce.com/?action=pcc_work_order_view&id=</nowiki>
|-
| URL Parameters
| <CMTLBLDATA_FLDTKTUSER1>
|}

===N-able™ N-central™===

'''Show Account and Asset information directly in N-central.'''

'''Contributed by ajgyomber'''

Note: You'll need to replace "server.n-able.com", "email@domain.com" and "your_actual_password" with your actual information.

{| class="wikitable"
|-
! Parameters
! Values
|-
| Data Source
| Accounts
|-
| Name
| N-central Dashboard
|-
| Base URL
| <nowiki>https://server.n-able.com/deepLinkAction.do</nowiki>
|-
| URL Parameters
| ?method=defaultDashboard&username=email@domain.com&password=your_actual_password
|}

{| class="wikitable"
|-
! Parameters
! Values
|-
| Data Source
| Assets
|-
| Name
| N-central Device Details
|-
| Base URL
| <nowiki>https://server.n-able.com/deepLinkAction.do</nowiki>
|-
| URL Parameters
| ?method=deviceDetails&username=email@domain.com&password=your_actual_password&customerID=<CMTLBLDATA_FLDASTACCRECID_FLDCRDCARDID3>&deviceID=<CMTLBLDATA_FLDASTUSER1>
|}

{| class="wikitable"
|-
! Parameters
! Values
|-
| Data Source
| Assets
|-
| Name
| N-central Device Services
|-
| Base URL
| <nowiki>https://server.n-able.com/deepLinkAction.do</nowiki>
|-
| URL Parameters
| ?method=deviceService&username=email@domain.com&password=your_actual_password&customerID=<CMTLBLDATA_FLDASTACCRECID_FLDCRDCARDID3>&deviceID=<CMTLBLDATA_FLDASTUSER1>
|}

{| class="wikitable"
|-
! Parameters
! Values
|-
| Data Source
| Assets
|-
| Name
| N-central Launch Remote Control
|-
| Base URL
| <nowiki>https://server.n-able.com/deepLinkAction.do</nowiki>
|-
| URL Parameters
| ?method=deviceRC&username=email@domain.com&password=your_actual_password&customerID=<CMTLBLDATA_FLDASTACCRECID_FLDCRDCARDID3>&deviceID=<CMTLBLDATA_FLDASTUSER1>
|}

{| class="wikitable"
|-
! Parameters
! Values
|-
| Data Source
| Accounts
|-
| Name
| N-central NOC View
|-
| Base URL
| <nowiki>https://server.n-able.com/deepLinkAction.do</nowiki>
|-
| URL Parameters
| ?method=nocView&username=email@domain.com&password =your_actual_password
|}

==Parameters list==

===Parameters List for Accounts===
{| class="wikitable"
|-
! Field Name
! Parameter Name to Use
|-
| Account Number
| <CMTLBLDATA_FLDCRDCARDID2>
|-
| Address: City
| <CMTLBLDATA_FLDCRDCITY>
|-
| Address: Country
| <CMTLBLDATA_FLDCRDCOUNTRY>
|-
| Address: Line1
| <CMTLBLDATA_FLDCRDADDRESS1>
|-
| Address: Line2
| <CMTLBLDATA_FLDCRDADDRESS2>
|-
| Address: Line3
| <CMTLBLDATA_FLDCRDADDRESS3>
|-
| Address: State
| <CMTLBLDATA_FLDCRDSTATE>
|-
| Address: ZIP Code
| <CMTLBLDATA_FLDCRDZIP>
|-
| Assistant
| <CMTLBLDATA_FLDCRDASSISTANT>
|-
| Birthday
| <CMTLBLDATA_FLDCRDBIRTHDAY>
|-
| Company name
| <CMTLBLDATA_FLDCRDCOMPANY>
|-
| Contact: First & Last Name
| <CMTLBLDATA_FLDCRDCONTACT>
|-
| Dear
| <CMTLBLDATA_FLDCRDDEAR>
|-
| Department
| <CMTLBLDATA_FLDCRDDEPARTMENT>
|-
| E-Mail Address 1
| <CMTLBLDATA_FLDCRDEMAIL1>
|-
| E-Mail Address 2
| <CMTLBLDATA_FLDCRDEMAIL2>
|-
| Fax Number
| <CMTLBLDATA_FLDCRDFAX1>
|-
| Fax Number Extention
| <CMTLBLDATA_FLDCRDFAXDESC1>
|-
| Field
| <CMTLBLDATA_FLDCRDPERSONID>
|-
| Field1
| <CMTLBLDATA_FLDCRDUSER2>
|-
| Field2
| <CMTLBLDATA_FLDCRDUSER3>
|-
| Field3
| <CMTLBLDATA_FLDCRDUSER4>
|-
| Field4
| <CMTLBLDATA_FLDCRDUSER5>
|-
| Field5
| <CMTLBLDATA_FLDCRDCOMPANYNO>
|-
| File as
| <CMTLBLDATA_FLDCRDFULLNAME>
|-
| ID
| <CMTLBLDATA_FLDCRDCARDID3>
|-
| Last Name
| <CMTLBLDATA_FLDCRDLASTNAME>
|-
| Phone 1
| <CMTLBLDATA_FLDCRDPHONE1>
|-
| Phone 1 Ext.
| <CMTLBLDATA_FLDCRDPHNDESC1>
|-
| Phone 2
| <CMTLBLDATA_FLDCRDPHONE2>
|-
| Phone 2 Ext.
| <CMTLBLDATA_FLDCRDPHNDESC2>
|-
| Phone 3
| <CMTLBLDATA_FLDCRDPHONE3>
|-
| Phone 3 Ext.
| <CMTLBLDATA_FLDCRDPHNDESC3>
|-
| Phone 4
| <CMTLBLDATA_FLDCRDPHONE4>
|-
| Phone 4 Ext.
| <CMTLBLDATA_FLDCRDPHNDESC4>
|-
| Popup Message
| <CMTLBLDATA_FLDCRDCARDMESSAGE>
|-
| Region
| <CMTLBLDATA_FLDCRDREGIONCODE>
|-
| Salutation
| <CMTLBLDATA_FLDCRDSUFFIX>
|-
| Status
| <CMTLBLDATA_FLDCRDUSER1>
|-
| Sub-Contact Code
| <CMTLBLDATA_FLDCRDSUBCODE>
|-
| Title
| <CMTLBLDATA_FLDCRDTITLE>
|-
| Type
| <CMTLBLDATA_FLDCRDKIND>
|-
| Web Address 1
| <CMTLBLDATA_FLDCRDURL1>
|-
| Web Address 2
| <CMTLBLDATA_FLDCRDURL2>
|}

===Parameters list for Assets===
{| class="wikitable"
|-
! Field Name
! Parameter Name to Use
|-
| Account ([[Commit Online Services#Lookup Fields|Lookup field]])
| <CMTLBLDATA_FLDASTACCRECID>
|-
| Asset Code
| <CMTLBLDATA_FLDASTASSETCODE>
|-
| Asset Type
| <CMTLBLDATA_FLDASTASSETTYPE>
|-
| Contact ([[Commit Online Services#Lookup Fields|Lookup field]])
| <CMTLBLDATA_FLDASTCONTACTRECID>
|-
| Create Date
| <CMTLBLDATA_FLDASTCREATEDATE>
|-
| Created by user
| <CMTLBLDATA_FLDASTCREATEUSER_FLDWRKNICKNAME>
|-
| Purchase Date
| <CMTLBLDATA_FLDASTCUSTPURDATE>
|-
| Purchased From Us
| <CMTLBLDATA_FLDASTCUSTPURFROMUS>
|-
| Purchase Our Invoice #
| <CMTLBLDATA_FLDASTCUSTPUROURINV>
|-
| Customer PO
| <CMTLBLDATA_FLDASTCUSTPURPO>
|-
| Purchase Price
| <CMTLBLDATA_FLDASTCUSTPURPRICE>
|-
| Delivered Date
| <CMTLBLDATA_FLDASTDELIVEDATE>
|-
| Description
| <CMTLBLDATA_FLDASTDESC>
|-
| Installed By
| <CMTLBLDATA_FLDASTINSTALBY_FLDWRKNICKNAME>
|-
| Installed Date
| <CMTLBLDATA_FLDASTINSTALDATE>
|-
| License Codes
| <CMTLBLDATA_FLDASTLICENSECODE>
|-
| License Keys
| <CMTLBLDATA_FLDASTLICENSEKEYS>
|-
| License Notes
| <CMTLBLDATA_FLDASTLICENSENOTES>
|-
| Location
| <CMTLBLDATA_FLDASTLOCATION>
|-
| Manufacturer
| <CMTLBLDATA_FLDASTMANUFACTURER>
|-
| Manufacturer Serial No.
| <CMTLBLDATA_FLDASTMNFSERIALNO>
|-
| Model
| <CMTLBLDATA_FLDASTMODEL>
|-
| Asset Name
| <CMTLBLDATA_FLDASTNAME>
|-
| Notes
| <CMTLBLDATA_FLDASTNOTES>
|-
| PARENTASSETRECID
| <CMTLBLDATA_FLDASTPARENTRECID>
|-
| Quantity
| <CMTLBLDATA_FLDASTQUANTITY>
|-
| Record ID
| <CMTLBLDATA_FLDASTRECID>
|-
| Serial No.
| <CMTLBLDATA_FLDASTSERIALNO>
|-
| Status
| <CMTLBLDATA_FLDCRDPHONE3>
|-
| Last Update date
| <CMTLBLDATA_FLDASTUPDATEDATE>
|-
| Last Update By
| <CMTLBLDATA_FLDASTUPDATEUSER_FLDWRKNICKNAME>
|-
| Field1
| <CMTLBLDATA_FLDASTUSER1>
|-
| Field2
| <CMTLBLDATA_FLDASTUSER2>
|-
| Field3
| <CMTLBLDATA_FLDASTUSER3>
|-
| Field4
| <CMTLBLDATA_FLDASTUSER4>
|-
| Field5
| <CMTLBLDATA_FLDASTUSER5>
|-
| Date1
| <CMTLBLDATA_FLDASTUSERDATE1>
|-
| Number1
| <CMTLBLDATA_FLDASTUSERNUMBER1>
|-
| Vendor Purchased Date
| <CMTLBLDATA_FLDASTVENDORDATEPURC>
|-
| Vendor Invoice #
| <CMTLBLDATA_FLDASTVENDORINVNO>
|-
| Vendor Name
| <CMTLBLDATA_FLDASTVENDORNAME>
|-
| Vendor PO
| <CMTLBLDATA_FLDASTVENDOROURPO>
|-
| Vendor Price
| <CMTLBLDATA_FLDASTVENDORPRICE>
|-
| Vendor
| <CMTLBLDATA_FLDASTVENDORRECID>
|-
| Vendor Serial No.
| <CMTLBLDATA_FLDASTVENDORSERNO>
|-
| Vendor Warranty Exp. Date
| <CMTLBLDATA_FLDASTVENDORWARREXP>
|-
| Version
| <CMTLBLDATA_FLDASTVERSION>
|-
| Warranty/License Exp. Date
| <CMTLBLDATA_FLDASTWARREXPDATE>FLDASTWARREXPDATE
|}

===Parameters list for Contracts===
{| class="wikitable"
|-
! Field Name
! Parameter Name to Use
|-
| Account ([[Commit Online Services#Lookup Fields|Lookup field]])
| <CMTLBLDATA_FLDBCTACCRECID>
|-
| Block - Used
| <CMTLBLDATA_FLDBCTAMOUNTUSED>
|-
| Code
| <CMTLBLDATA_FLDBCTCODE>
|-
| Contract Type Type
| <CMTLBLDATA_FLDBCTCONTRACTTYPE>
|-
| Create Date
| <CMTLBLDATA_FLDBCTCREATEDATE>
|-
| Created by user
| <CMTLBLDATA_FLDBCTCREATEUSER_FLDWRKNICKNAME>
|-
| Default Item Expense ([[Commit Online Services#Lookup Fields|Lookup field]])
| <CMTLBLDATA_FLDBCTDEFITMEXPNS>
|-
| Default Item Labor ([[Commit Online Services#Lookup Fields|Lookup field]])
| <CMTLBLDATA_FLDBCTDEFITMLABOR>
|-
| Default Item Part ([[Commit Online Services#Lookup Fields|Lookup field]])
| <CMTLBLDATA_FLDBCTDEFITMPART>
|-
| Description
| <CMTLBLDATA_FLDBCTDESCEXTERNAL>
|-
| Internal Description
| <CMTLBLDATA_FLDBCTDESCINTERNAL>
|-
| End Date
| <CMTLBLDATA_FLDBCTENDDATE>
|-
| Name
| <CMTLBLDATA_FLDBCTNAME>
|-
| Note
| <CMTLBLDATA_FLDBCTNOTE>
|-
| Record ID
| <CMTLBLDATA_FLDBCTRECID>
|-
| Start Date
| <CMTLBLDATA_FLDBCTSTARTDATE>
|-
| Status
| <CMTLBLDATA_FLDBCTSTATUS>
|-
| Last Update date
| <CMTLBLDATA_FLDBCTUPDATEDATE>
|-
| Last Updated by User
| <CMTLBLDATA_FLDBCTUPDATEUSER_FLDWRKNICKNAME>
|-
| Field 1
| <CMTLBLDATA_FLDBCTUSER1>
|-
| Field 2
| <CMTLBLDATA_FLDBCTUSER2>
|-
| Field 3
| <CMTLBLDATA_FLDBCTUSER3>
|}

===Parameters list for Items===
{| class="wikitable"
|-
! Field Name
! Parameter Name to Use
|-
| Currency
| <CMTLBLDATA_FLDITMCOINID>
|-
| Created by User
| <CMTLBLDATA_FLDITMCREATEUSER_FLDWRKNICKNAME>
|-
| Description
| <CMTLBLDATA_FLDITMDESC>
|-
| Expense Type
| <CMTLBLDATA_FLDITMEXPITEMTYPE>
|-
| Labor Type
| <CMTLBLDATA_FLDITMFEEITEMTYPE>
|-
| Item Code
| <CMTLBLDATA_FLDITMITEMNO>
|-
| Group
| <CMTLBLDATA_FLDITMITEMTYPEGROUP>
|-
| Name
| <CMTLBLDATA_FLDITMNAME>
|-
| Notes
| <CMTLBLDATA_FLDITMNOTES>
|-
| Price Source
| <CMTLBLDATA_FLDITMPRICESOURCE>
|-
| Product/Part Type
| <CMTLBLDATA_FLDITMPRODITEMTYPE>
|-
| Record Id
| <CMTLBLDATA_FLDITMRECID>
|-
| Cost
| <CMTLBLDATA_FLDITMSTANDARDCOST>
|-
| Suspend
| <CMTLBLDATA_FLDITMSUSPENDED>
|-
| Price
| <CMTLBLDATA_FLDITMUNITPRICE>
|-
| Update Date
| <CMTLBLDATA_FLDITMUPDATEDATE>
|-
| Update User
| <CMTLBLDATA_FLDITMUPDATEUSER_FLDWRKNICKNAME>
|-
| Field1
| <CMTLBLDATA_FLDITMUSER1>
|}

===Parameters list for Opportunities===
{| class="wikitable"
|-
! Field Name
! Parameter Name to Use
|-
| Amount
| <CMTLBLDATA_FLDOPPAMOUNT>
|-
| Amount by Probability
| <CMTLBLDATA_FLDOPPCALCAMOUNT>
|-
| Account ([[Commit Online Services#Lookup Fields|Lookup field]])
| <CMTLBLDATA_FLDOPPCARDID>
|-
| Closing amnt
| <CMTLBLDATA_FLDOPPCLOSEAMOUNT>
|-
| Close
| <CMTLBLDATA_FLDOPPCLOSEDATE>
|-
| Currency
| <CMTLBLDATA_FLDOPPCOINID>
|-
| Contact ([[Commit Online Services#Lookup Fields|Lookup field]])
| <CMTLBLDATA_FLDOPPCONTACTID>
|-
| Creation Date
| <CMTLBLDATA_FLDOPPCREATEDATE>
|-
| Created by User
| <CMTLBLDATA_FLDOPPCREATEUSER_FLDWRKNICKNAME>
|-
| Description
| <CMTLBLDATA_FLDOPPDESCRIPTION>
|-
| Close By
| <CMTLBLDATA_FLDOPPESTDATE>
|-
| Oppty Type
| <CMTLBLDATA_FLDOPPKIND>
|-
| Opportunity
| <CMTLBLDATA_FLDOPPNAME>
|-
| Note
| <CMTLBLDATA_FLDOPPNOTES>
|-
| Open
| <CMTLBLDATA_FLDOPPOPENDATE>
|-
| Probability %
| <CMTLBLDATA_FLDOPPPROBABILITY>
|-
| Reason
| <CMTLBLDATA_FLDOPPREASON>
|-
| Record ID
| <CMTLBLDATA_FLDOPPRECID>
|-
| Record type
| <CMTLBLDATA_FLDOPPRECKIND>
|-
| Territory
| <CMTLBLDATA_FLDOPPREGION>
|-
| Source
| <CMTLBLDATA_FLDOPPSOURCE>
|-
| Stage
| <CMTLBLDATA_FLDOPPSTAGE>
|-
| Status
| <CMTLBLDATA_FLDOPPSTATUS>
|-
| Last Update Date
| <CMTLBLDATA_FLDOPPUPDATEDATE>
|-
| Last Update: By User
| <CMTLBLDATA_FLDOPPUPDATEUSER_FLDWRKNICKNAME>
|-
| Field1
| <CMTLBLDATA_FLDOPPUSER1>
|-
| Field2
| <CMTLBLDATA_FLDOPPUSER2>
|-
| Field3
| <CMTLBLDATA_FLDOPPUSER3>
|-
| Opportunity ID
| <CMTLBLDATA_FLDOPPUSERID>
|-
| Manager
| <CMTLBLDATA_FLDOPPWORKERID_FLDWRKNICKNAME>
|}

===Parameters list for Tickets===
{| class="wikitable"
|-
! Field Name
! Parameter Name to Use
|-
| Asset ([[Commit Online Services#Lookup Fields|Lookup field]])
| <CMTLBLDATA_FLDTKTASSETRECID>
|-
| Contract ([[Commit Online Services#Lookup Fields|Lookup field]])
| <CMTLBLDATA_FLDTKTBCRECID>
|-
| Account ([[Commit Online Services#Lookup Fields|Lookup field]])
| <CMTLBLDATA_FLDTKTCARDID>
|-
| Category
| <CMTLBLDATA_FLDTKTCATEGORY>
|-
| Cause
| <CMTLBLDATA_FLDTKTCAUSE>
|-
| Close Date
| <CMTLBLDATA_FLDTKTCLOSEDATETIME>
|-
| Contact ([[Commit Online Services#Lookup Fields|Lookup field]])
| <CMTLBLDATA_FLDTKTCONTACTID>
|-
| Creation: Date
| <CMTLBLDATA_FLDTKTCREATEDATE>
|-
| Created by user
| <CMTLBLDATA_FLDTKTCREATEUSER_FLDWRKNICKNAME>
|-
| Due Date
| <CMTLBLDATA_FLDTKTDUEDATETIME>
|-
| Ticket Type
| <CMTLBLDATA_FLDTKTKIND>
|-
| Notes
| <CMTLBLDATA_FLDTKTNOTES>CMTLBLDATA
|-
| Open Date
| <CMTLBLDATA_FLDTKTOPENDATETIME>
|-
| Priority
| <CMTLBLDATA_FLDTKTPRIORITY>
|-
| Description
| <CMTLBLDATA_FLDTKTPROBLEM>
|-
| Record ID
| <CMTLBLDATA_FLDTKTRECID>
|-
| Account's Region Code
| <CMTLBLDATA_FLDTKTREGIONCODE>
|-
| Estimated Duration Needed
| <CMTLBLDATA_FLDTKTSCHEDLENESTIM>
|-
| Resolution Description
| <CMTLBLDATA_FLDTKTSOLUTION>
|-
| Source
| <CMTLBLDATA_FLDTKTSOURCE>
|-
| Status
| <CMTLBLDATA_FLDTKTSTATUS>
|-
| Status: Ext.
| <CMTLBLDATA_FLDTKTSTATUSNOTE>
|-
| Ticket Number
| <CMTLBLDATA_FLDTKTTICKETNO>
|-
| Last Update Date
| <CMTLBLDATA_FLDTKTUPDATEDATE>
|-
| Last Updated by User
| <CMTLBLDATA_FLDTKTUPDATEUSER_FLDWRKNICKNAME>
|-
| Field1
| <CMTLBLDATA_FLDTKTUSER1>
|-
| Field2
| <CMTLBLDATA_FLDTKTUSER2>
|-
| Field3
| <CMTLBLDATA_FLDTKTUSER3>
|-
| Manager
| <CMTLBLDATA_FLDTKTWORKERID_FLDWRKNICKNAME>
|}

===Parameters list for Tickets===
{| class="wikitable"
|-
! Field Name
! Parameter Name to Use
|-
| Category
| <CMTLBLDATA_FLDKBACATEGORY>
|-
| Create Date
| <CMTLBLDATA_FLDKBACREATEDATE>
|-
| Created by user
| <CMTLBLDATA_FLDKBACREATEUSER_FLDWRKNICKNAME>
|-
| Public
| <CMTLBLDATA_FLDKBAISPUBLIC>
|-
| Problem
| <CMTLBLDATA_FLDKBAPROBLEM>
|-
| Record ID
| <CMTLBLDATA_FLDKBARECID>
|-
| Solution
| <CMTLBLDATA_FLDKBASOLUTION>
|-
| Status
| <CMTLBLDATA_FLDKBASTATUS>
|-
| Title
| <CMTLBLDATA_FLDKBATITLE>
|-
| Last Update date
| <CMTLBLDATA_FLDKBAUPDATEDATE>
|-
| Last Update By
| <CMTLBLDATA_FLDKBAUPDATEUSER_FLDWRKNICKNAME>
|}

===Lookup Fields===
*Lookup Fields can be used in order to pass parameters from an entity which is linked to the entity you are currently using. For example, you can create an Online Service for a Ticket, and pass the address of the account which is linked to the ticket. This way you can define an Online Service for the Account, which will be activated from the Ticket window. Lookup Field syntax: <CMTLBLDATA_FLDTKTCARDID_FLDCRDADDRESS1> Where:
CMTLBLDATA_FLDTKTCARDID is the pointer to the linked account FLDCRDADDRESS1 is the account's Address field

==See Also==
*[[Online Services FAQ]]

[[Category:Integration]]

API Reference Manual

2010-02-23T14:22:19Z

Reno: /* Item Fields */

{{usermanualsapidevelopersguide}}
==Intorduction==

Following is a detailed listing of fields per entity which can be added/updated using the API. The API parameters are the same when using the Programming API or the XML API.

The API allows you to add/update the following entities:
*[[#Account Fields|Accounts]]
*[[#Ticket Fields|Tickets]]
*[[#Charge Fields|Charges (and Contract-price Charges)]]
*[[#Item Fields|Items]]
*[[#History Note Fields|History Notes]]
*[[#Asset Fields|Assets]]
*[[#Calendar Fields|Calender]]
*[[#Opportunity Fields|Opportunities]]
*[[#Document Fields|Documents]]
*[[#Knowledge Base Article Fields|Knowledge Base Articles]]

All API functions may return error codes. You can find the possible error codes in:
*[[#Error Codes Description|Error Codes]]

In the following section you will find a detailed listing of the database fields. Each table includes the fields '''Display name''' (as shows in the application), the '''Database Field Name''' (internal database field identifier) and comments.

Note that when using XML formatted messages, the database field name refers to the name to be provided within the XML token. For example, when the field name is FLDSLPQUANTITY, the XML token should look like this:
<FLDSLPQUANTITY>10</FLDSLPQUANTITY>

The following table shows the data kind code when using XML or when using the API functions:

{| class="wikitable"
|-
! '''Application entity'''
! '''Table name'''
! '''Programming Code'''
! '''XML Data Kind Name'''
|-
| Accounts
| Cards
| 10
| ACCOUNT
|-
| Opportunities
| Opps
| 20
| OPPORTUNITY
|-
| Documents
| Docs
| 30
| DOCUMENT
|-
| Charges
| Slips
| 40
| CHARGE
|-
| Appointments/Tasks
| Events
| 50
| APPOINTMENT-OR-TASK
|-
| History Notes
| Notebook
| 60
| HISTORY-NOTE
|-
| Tickets
| Tickets
| 70
| TICKET
|-
| Items
| Items
| 80
| ITEM
|-
| Assets
| Assets
| 90
| ASSET
|-
| Knowledge Base
| KBArticles
| 100
| KBARTICLE
|}
You can find examples of adding and updating records in the database by using the database field in the [[API Code Samples]] section.

===Account Fields===
The following table lists the most important parameters for adding/updating Account
records.
Note slight differences when adding a main account vs. adding a secondary contact.

{| class="wikitable"
|-
! '''Field Name'''
! '''Database Field Name'''
! '''Comment'''
|-
| Account REC ID
| FLDCRDRECID
|The Account record ID (20 chars). The Account Rec ID can be taken from:
#Account Notes tab, at the bottom, rightclick the RecID field and use Copy. e.g. CRDVQYSOD1B4U4HZIQJJ
#Using ODBC to pull information from the database.
#From the Email Response when adding new Account with the API.
|-
| Account Manager
| FLDCRDASSIGNCARDID
| This field has two roles:
#When adding a main Account: The account manager should contain the ID of the Employee who is the account manager.
#When adding a secondary contact: 
This field should contain the ID of the main Account to which the secondary contacted is
added.
|-
|Company name
|FLDCRDCOMPANY
|
|-
|Contact: First & Last Name
|FLDCRDCONTACT
|
|-
| Assistant
| FLDCRDASSISTANT
|
|-
|Contract
|FLDCRDBCRECID
|The default Contract for this Account (not required)
|-
|Account Number
|FLDCRDCARDID2
|
|-
|ID
|FLDCRDCARDID3
|
|-
|Popup Message
|FLDCRDCARDMESSAGE
|
|-
| Address: Line1
| FLDCRDADDRESS1
|
|-
| Address: Line2
| FLDCRDADDRESS2
|
|-
| Address: Line3
| FLDCRDADDRESS3
|
|-
|Address: City
|FLDCRDCITY
|
|-
|Address: State
|FLDCRDCOUNTRY
|
|-
|Address: Country
|FLDCRDSTATE
|
|-
|Address: Zip
|FLDCRDZIP
|
|-
|Creation Date
|FLDCRDCREATEDATE
|Any date format, such as DD/MM/YYYY
|-
|Created by User
|FLDCRDCREATEUSERID
|Foreign Software Name which created the account
|-
|Dear
|FLDCRDDEAR
|
|-
|Department
|FLDCRDDEPARTMENT
|
|-
|Documents Store Directory
|FLDCRDDOCSFOLDER
|
|-
|E-Mail Address 1
|FLDCRDEMAIL1
|
|-
|E-Mail Address 2
|FLDCRDEMAIL2
|
|-
|Account Type
|FLDCRDENTITYKIND
|When adding a Main Account = 1 When adding a secondary contact = 5
|-
|Fax Number
|FLDCRDFAX1
|
|-
|Fax Number Extension
|FLDCRDFAXDESC1
|
|-
|File as
|FLDCRDFULLNAME
|
|-
|Type
|FLDCRDKIND
|
|-
|Last Name
|FLDCRDLASTNAME
|
|-
|Notes
|FLDCRDNOTES
|
|-
|Field
|FLDCRDPERSONID
|
|-
|Phone 1 Ext.
|FLDCRDPHNDESC1
|
|-
|Phone 2 Ext.
|FLDCRDPHNDESC2
|
|-
|Phone 3 Ext.
|FLDCRDPHNDESC3
|
|-
|Phone 4 Ext.
|FLDCRDPHNDESC4
|
|-
|Phone 1
|FLDCRDPHONE1
|
|-
|Phone 2
|FLDCRDPHONE2
|
|-
|Phone 3
|FLDCRDPHONE3
|
|-
|Phone 4
|FLDCRDPHONE4
|
|-
|Region
|FLDCRDREGIONCODE
|
|-
|Popup Message: Display Indication
|FLDCRDSHOWMESSAGE
|
|-
|Sub-Contact Code
|FLDCRDSUBCODE
|
|-
|Salutation
|FLDCRDSUFFIX
|
|-
|Tax1
|FLDCRDTAXCODE1
|
|-
|Tax2
|FLDCRDTAXCODE2
|
|-
|Notes
|FLDCRDNOTES
|
|-
|Title
|FLDCRDTITLE
|
|-
|Last Updated by
|FLDCRDUPDATEUSERID
|When performing updates on existing Account - pass the Foreign Software Name which performs the update.
|-
|Web Address 1
|FLDCRDURL1
|
|-
|Web Address 2
|FLDCRDURL2
|
|-
|Status
|FLDCRDUSER1
|
|-
|Field1
|FLDCRDUSER2
|
|-
|Field2
|FLDCRDUSER3
|
|-
|Field3
|FLDCRDUSER4
|
|-
|Field4
|FLDCRDUSER5
|
|}

===Ticket Fields===

The table below lists the most important Ticket parameters and behavior:

{| class="wikitable"
|-
! '''Field Name'''
! '''Database Field Name'''
! '''Comment'''
|-
| Account REC ID
| FLDTKTCARDID
|The Account record ID (20 chars). The Account Rec ID can be taken from:
#Account Notes tab, at the bottom by rightclicking the REC ID field and selecting Copy
#ODBC to pull information from the database
#The automated email response when adding a cnew Account with the API
|-
| Contact REC ID
| FLDTKTCONTACTID
|The Contact for this Account. If not provided, the main Contact for the Account is taken.
|-
| Contract REC ID
| FLDTKTBCRECID
|The Contract ID. If not supplied, will be taken from the Account's default contract.
|-
| Emp. REC ID
| FLDTKTWORKERID
|The worker ID to be linked to the Ticket. Must be an active employee. This is an optional parameter. If not passed, the system default will be used.
|-
| Priority
| FLDTKTPRIORITY
| The ticket priority. If not passed in the transaction, the default value for new Tickets will be used.
Immediate = 10 High = 20 Normal = 30 Low = 40 Not Applicable= 50
|-
| Ticket Number
| FLDTKTTICKETNO
| The Ticket number. If passed, must be an existing Ticket, and this will update the Ticket with the details in the transaction.
|-
|Description
|FLDTKTPROBLEM
|This is the Ticket Description. This is a mandatory field, which must contain text.
|-
|Ticket Type
|FLDTKTKIND
|Ticket Type (optional). The Ticket Type string should be passed. If not provided, default is used.
|-
|Source
|FLDTKTSOURCE
|
|-
|Estimated Duration Time
|FLDTKTSCHEDLENESTIM
|Estimated duration time for the Ticket in minutes.
|-
|Show Ticket in Dispatcher
|FLDTKTFORDISPATCH
|Possible values: Yes/No
|-
|Status
|FLDTKTSTATUS
|The Ticket Status (optional). 
Possible values: 
New = 100 
Pending = 200 
Scheduled = 300 
In-House Service = 400 
On-Site Service = 500 
Laboratory Service = 600 
Hold = 700 
Other = 800 
Canceled = 900 
Completed = 1000
|-
|Created by User
|FLDTKTCREATEUSER
|Should contain the external software name which created the Ticket
|-
|Due Date
|FLDTKTDUEDATETIME
|Due date for the Ticket. Should be passed in date format. e.g. MM/DD/YYYY
|-
|Resolution
|FLDTKTSOLUTION
|Ticket resolution text
|}

===Charge Fields===
The table below lists the most important Charge parameters and behavior.

Contract-price Charges have some special characteristics (see comments marked by * in
the table below):

{| class="wikitable"
|-
! '''Field Name'''
! '''Database Field Name'''
! '''Comment'''
|-
| Record ID
| FLDSLPRECID
|The Charge record ID. If provided, the existing Charge will be updated. Otherwise, this will be
added as a new Charge.
|-
| Charge Source
| FLDSLPSOURCERECID
|The Charge source is the entity for which the charge is created. 
Possible values:
*Linked Contract RecID (for Contract-price Charges). Cannot be the "System Global Contract".
**Passing the Contract RecID indicates that this is a Contract-price charge.
*Entity RecID from which the charge is created (for example when creating a charge from an Appointment or Task).
|-
| Account REC ID
| FLDSLPCARDID
|The Account record ID (20 chars). The Account REC ID can be taken from:
#Account Notes tab, at the bottom by rightclicking the REC ID field and selecting Copy
#ODBC to pull information from the database
#The automated email response when adding a new Account with the API
|-
| Employee REC ID
| FLDSLPWORKERID
| The worker record ID to be linked to the Charge. Must be an active employee. This is an optional parameter. If not passed, the system default will be used.
|-
| Charged Item
| FLDSLPITEMID
| The Item Record ID to be linked to the Charge. This is a mandatory field.
*For Contract-price Charge can be only Fixed-Price, Unit-based Item.
|-
| Contract REC ID
| FLDSLPBCRECID
| The contract record ID (must be a Contract of the Account)
|-
|Ticket REC ID
|FLDSLPTICKETID
|The Ticket ID to be linked to the Charge.
*Not relevant for Contract-price Charge
|-
|Date
|FLDSLPSLIPDATE
|The date for the Charge. This is an optional parameter. If not provided, the current date will
be used. Should be passed in date format. e.g. MM/DD/YYYY
|-
|Description
|FLDSLPDESC
|The Charge Description. If not provided, will be taken from the Item's description.
|-
|Units/Hours
|FLDSLPQUANTITY
|This is the quantity of hours/units
|-
|Adjust Amount
|FLDSLPADJUSTAMOUNT
|Discount/Markup amount. Positive number means Markup, negative number means Discount.
|-
|Adjust Percent
|FLDSLPADJUSTPERCENT
|Discount/Markup in percentage, must be between (-100) - 100. Positive number means Markup, negative number means Discount.
|-
|From Time
|FLDSLPSTARTTIME
|From time for labor Charges e.g. 12:06
*Not relevant for Contract-price Charge
|-
|To Time
|FLDSLPENDTIME
|From time for labor Charges e.g. 14:50
* Not relevant for Contract-price Charge
|-
|Price/Rate
|FLDSLPPRICE
|If not provided, the price is taken from the Item.
|-
| Billable
| FLDSLPBILLKIND
| B - Billable 
N - Not Billable 
If not provided, will be set according to the Contract type.
|-
| Billed
| FLDSLPSTAGE
| D - Draft
B - Billed
|-
| Field1
| FLDSLPUSER1
| User defined field
|-
| Create User
| FLDSLPCREATEUSER
| External software name which created the Charge
|}

===Item Fields===

The table below lists the most important Item parameters and behavior:

{| class="wikitable"
|-
! '''Field Name'''
! '''Database Field Name'''
! '''Comment'''
|-
| Record ID
| FLDITMRECID
|The Item record ID. If provided, the existing item will be updated. Otherwise, this will be added as a new item.
|-
| Item Group
| FLDITMITEMTYPEGROUP
|The Item Group to be linked to the Charge. This is a mandatory field: 
F - Labor (Fee) 
X - Expense 
P - Part
|-
| Item Code
| FLDITMITEMNO
|The item code is a mandatory field
|-
| Item Name
| FLDITMNAME
| The item name is a mandatory field
|-
| Price Source
| FLDITMPRICESOURCE
| F - Fixed Price 
W - by Employee Rate
|-
| Price per Hour/Unit
| FLDITMUNITISHOUR
| This field indicated whether the price is unitbased or hours-based. 
Y - by Hours 
N - by Units 
This is an optional field, depending on the Item Group. For example, if the item group is Labor, and Price Source is By Employee, the value will always be by hours
|-
|Price
|FLDITMUNITPRICE
|Must be a valid numeric value
|-
|Cost
|FLDITMSTANDARDCOST
|The date for the Charge. This is an optional parameter. If not provided, the current date will
be used. Should be passed in date format. e.g. MM/DD/YYYY
|-
|Taxes
|FLDITMTAXCODE1 
FLDITMTAXCODE2 
FLDITMTAXCODE3
|You can pass up to 3 different tax codes.
|-
|Description by Name
|FLDITMDESCBYNAME
|Y - take the description from the name field 
N - take the description from the Description field
|-
|Description
|FLDITMDESC
|If not provided, the description is taken from the name.
|-
|Suspend
|FLDITMSUSPENDED
|Indicated whether this item is currently suspended: 
Y - yes 
N - no
|-
|Notes
|FLDITMNOTES
|
|-
|Field1
|FLDITMUSER1
|User defined field
|-
|Create User
|FLDITMCREATEUSER
|External software name which created the Charge
|-
| Created by User
| FLDTKTCREATEUSER
| Should contain the external software name which created the Ticket
|}

===History Note Fields===
The table below lists the most important History Note parameters and behavior:

{| class="wikitable"
|-
! '''Field Name'''
! '''Database Field Name'''
! '''Comment'''
|-
| Record ID
| FLDHISRECID
|The History Note record ID. If provided, the existing History Note will be updated. otherwise, this will be added as a new History Note.
|-
| Date
| FLDHISNOTEDATETIME
|Any date format, such as DD/MM/YYYY
|-
| Description
| FLDHISDESCRIPTION
| The Description text
|-
| Opportunity/Ticket/Contract
| FLDHISLINKRECID
| Link to Opportunity or Ticket or Contract
|-
| Field
| FLDHISUSER1
| User defined field
|-
| About
| FLDHISKIND
| Optional field
|-
|Employee
|FLDHISWORKERID
|The worker ID to be linked to the Ticket. Must be an active employee. This is an optional parameter. If not passed, the system default will be used.
|-
|Account
|FLDHISCARDID
|The Account record ID (20 chars). The Account Rec ID can be taken from:
#Account Notes tab, at the bottom, right-click the REC ID field and use Copy. e.g. CRDVQYSOD1B4U4HZIQJJ
#Using ODBC to pull information from the database
#From the Email Response when adding new Account with the API
|-
|Contact
|FLDHISCONTACTID
|The Contact for this Account. If not provided, the main Contact for the Account is taken.
|-
|Document
|FLDHISDOCID
|Linked Document ID, can be taken from the Document Properties window (right-click RecID and use Copy), or using the ODBC to pull information from the database.
|-
|Created by User
|FLDHISCREATEUSER
|Name of the external software which created this History Note
|}

===Asset Fields===
The table below lists the most important Asset parameters and behavior:

{| class="wikitable"
|-
! '''Field Name'''
! '''Database Field Name'''
! '''Comment'''
|-
| Asset Code
| FLDASTASSETCODE
|If an existing Asset Code is provided, then existing Asset is updated. Otherwise a new Asset is added.
|-
| Asset Type
| FLDASTASSETTYPE
|The Type field is mandatory: 
Hardware = H 
Software = S 
Other = T
|-
| Asset Name
| FLDASTNAME
|
|-
| Status
| FLDASTSTATUS
| Mandatory field. 
Active = A 
Not Active = N 
If not provided, default Active is used.
|-
| Record ID
| FLDASTRECID
| If provided, must exist in the database. Ignored if empty
|-
| Serial No.
| FLDASTSERIALNO
|
|-
|Account
|FLDASTACCRECID
|The Account which is linked to the Asset
|-
|Contact
|FLDASTCONTACTRECID
|The Contact for this Account. If not provided, the main Contact for the Account is taken.
|-
|Created by user
|FLDASTCREATEUSER
|Name of external software which created this Asset
|-
|Purchase Date
|FLDASTCUSTPURDATE
|Any date format, such as DD/MM/YYYY
|-
|Purchased From Us
|FLDASTCUSTPURFROMUS
|Possible values: Y/N. 
If not provided, default value Y is used.
|-
| Purchase Invoice #
| FLDASTCUSTPUROURINV
|
|-
| Customer PO
| FLDASTCUSTPURPO
|
|-
| Purchase Price
| FLDASTCUSTPURPRICE
|
|-
| Delivered Date
| FLDASTDELIVEDATE
|
|-
| Description
| FLDASTDESC
|
|-
| Installed By
| FLDASTINSTALBY
|
|-
| Installed Date
| FLDASTINSTALDATE
|
|-
| License Codes
| FLDASTLICENSECODE
|
|-
| License Keys
| FLDASTLICENSEKEY
|
|-
| License Notes
| FLDASTLICENSENOTES
|
|-
| Location
| FLDASTLOCATION
|
|-
| Manufacturer
| FLDASTMANUFACTURER
|
|-
| Mnf Serial No.
| FLDASTMNFSERIALNO
|
|-
| Model
| FLDASTMODEL
|
|-
| Notes
| FLDASTNOTES
|
|-
| Quantity
| FLDASTQUANTITY
| If not provided, default value of 1 is used.
|-
| Last Update By
| FLDASTUPDATEUSER
| Name of externals software which performed the update
|-
| Field1
| FLDASTUSER1
| User defined field
|-
| Field2
| FLDASTUSER2
| User defined field
|-
| Field3
| FLDASTUSER3
| User defined field
|-
| Field4
| FLDASTUSER4
| User defined field
|-
| Field5
| FLDASTUSER5
| User defined field
|-
| Date1
| FLDASTUSERDATE1
| User defined field
|-
| Number1
| FLDASTUSERNUMBER1
| User defined field
|-
| Vendor Purchased Date
| FLDASTVENDORDATEPURC
|
|-
| Vendor Invoice #
| FLDASTVENDORINVNO
|
|-
| Vendor PO
| FLDASTVENDOROURPO
|
|-
| Vendor Price
| FLDASTVENDORPRICE
|
|-
| Vendor
| FLDASTVENDORRECID
|
|-
| Vendor Serial No.
| FLDASTVENDORSERNO
|
|-
| Vendor Warranty Exp. Date
| FLDASTVENDORWARREXP
| Any date format, such as DD/MM/YYYY
|-
| Version
| FLDASTVERSION
|
|-
| Warranty/License Exp.
| FLDASTWARREXPDATE
| Any date format, such as DD/MM/YYYY
|-
| Date
|
|
|}

===Calendar Fields===
The table below lists the most important Calendar parameters and behavior:

{| class="wikitable"
|-
! '''Field Name'''
! '''Database Field Name'''
! '''Comment'''
|-
| Record ID
| FLDEVTRECID
|The Appointment/Task record ID. If provided, the existing entity will be updated. Otherwise, this
will be added as a new Appointment/Task.
|-
| Event Type
| FLDEVTWRITETOID
|The Event type is a mandatory field. 
Appointment = 1 
Task = 2
|-
| Employee
| FLDEVTWORKERID
| The Task/Appointment owner (for private events)
|-
| Private: User
| FLDEVTPRIVATEID
| Possible values: Y/N 
If an Employee was set, this field must be Y
|-
| Account
| FLDEVTCARDID
| The Account record ID (20 chars). The Account REC ID can be taken from:
#Account Notes tab, at the bottom by rightclicking
the REC ID field and selecting Copy
#ODBC to pull information from the database
#The automated email response when adding a
new Account with the API
|-
| Contact
| FLDEVTCONTACTID
| The Contact for this Account. If not provided, the main Contact for the Account is taken.
|-
|Document
|FLDEVTDOCID
|Linked Document ID, can be taken from the Document Properties window (right-click RecID and use Copy), or using the ODBC to pull information from the database.
|-
|Done Indication
|FLDEVTDONE
|Possible values: Y/N
|-
|Date
|FLDEVTEVENTDATE
|The Appointment/Task date is a mandatory field of Any date format, such as DD/MM/YYYY. If not
provided, the current date will be used.
|-
|Description
|FLDEVTFREETEXT
|
|-
|Time: Start
|FLDEVTFROMTIME
|Mandatory field
|-
| Time: End
| FLDEVTTOTIME
| Relevant only for Appointments. If this parameter is not provided, 30 min. interval from Start Time is used.
|-
| Opportunity/Ticket
| FLDEVTLINKRECID
| Linked Ticket/Opportunity/Contract/Asset
|-
| Field1
| FLDEVTFAMILY
| User Defined field
|-
| Field2
| FLDEVTACTION
| User Defined field
|-
| Field3
| FLDEVTPLACE
| User Defined field
|-
| Field4
| FLDEVTPLACE1
| User Defined field
|-
| Field5
| FLDEVTPLACE2
| User Defined field
|-
| Created by User
| FLDEVTCREATEUSERID
| Name of external software which created the event
|-
| Last Update: By User
| FLDEVTUPDATEUSER
| Name of external software which updated the
event
|}

===Opportunity Fields===
The table below lists the most important Opportunity parameters and behavior:

{| class="wikitable"
|-
! '''Field Name'''
! '''Database Field Name'''
! '''Comment'''
|-
| Record ID
| FLDOPPRECID
| The Opportunity record ID. If provided, the existing Opportunity will be updated. Otherwise, this will be added as a new Opportunity.
|-
| Opportunity Name
| FLDOPPNAME
| Mandatory field.
|-
| Opportunity ID
| FLDOPPUSERID
| Optional (Oppty ID)
|-
| Account
| FLDOPPCARDID
| The Account record ID (20 chars). The Account REC ID can be taken from:
#Account Notes tab, at the bottom by right-clicking the REC ID field and selecting Copy
#ODBC to pull information from the database
#The automated email response when adding a new Account with the API
|-
| Contact
| FLDEVTCONTACTID
| The Contact for this Account. If not provided, the main Contact for the Account is taken.
|-
| Source
| FLDOPPSOURCE
|
|-
|Document
|FLDEVTDOCID
|Linked Document ID, can be taken from the Document Properties window (right-click RecID and use Copy), or using the ODBC to pull information from the database.
|-
|Done Indication
|FLDEVTDONE
|Possible values: Y/N
|-
|Close Date
|FLDOPPCLOSEDATE
|
|-
|Manager
|FLDOPPWORKERID
|The Manager's REC ID
|-
|Open Date
|FLDOPPOPENDATE
|
|-
| Close By Date
| FLDOPPESTDATE
| Opportunity must be closed by this date
|-
| Amount
| FLDOPPAMOUNT
|
|-
| Probability %
| FLDOPPPROBABILITY
|
|-
| Stage
| FLDOPPSTAGE
|
|-
| Status
| FLDOPPSTATUS
|
|-
| Closing Amount
| FLDOPPCLOSEAMOUNT
|
|-
| Description
| FLDOPPDESCRIPTION
|
|-
| Opportunity Type
| FLDOPPKIND
|
|-
| Opportunity Reason
| FLDOPPREASON
|
|-
| Note
| FLDOPPNOTES
|
|-
| Territory
| FLDOPPREGION
|
|-
| Field1
| FLDEVTFAMILY
| User Defined field
|-
| Field2
| FLDEVTACTION
| User Defined field
|-
| Field3
| FLDEVTPLACE
| User Defined field
|-
| Created by User
| FLDEVTCREATEUSERID
| Name of external software which created the event
|-
| Last Update: By User
| FLDEVTUPDATEUSER
| Name of external software which updated the event
|}

===Document Fields===
The table below lists the Document parameters and behavior:

{| class="wikitable"
|-
! '''Field Name'''
! '''Database Field Name'''
! '''Comment'''
|-
| Record ID
| FLDDOCRECID
| The Document record ID. If provided, the existing Document will be updated. Otherwise, this will be added as a new Document.
|-
| Document Date
| FLDDOCDOCDATE
| The date for the Document. This is an optional parameter. If not provided, or if the value is illegal, the current date will be used. Should be passed in date format. e.g. MM/DD/YYYY
|-
| Subject
| FLDOPPUSERID
|
|-
| Linked Record
| FLDDOCLINKRECID
| The RECID of a linked object. Each Document can be linked to one of the following objects:
*Ticket
*Contract
*Opportunity
*Knowledge Base Article
*Asset
The Record ID (20 chars) can be taken from:
#Object's Notes tab, at the bottom by right-clicking the REC ID field and selecting Copy
#ODBC to pull information from the database
#The automated email response when adding a new object with the API.
|-
| Account Rec ID
| FLDDOCCARDID
| The Account record ID (20 chars). The Account REC ID can be taken from:
#Account Notes tab, at the bottom by right-clicking the REC ID field and selecting Copy
#ODBC to pull information from the database
#The automated email response when adding a new Account with the API
|-
| Contact REC ID
| FLDDOCCONTACTID
| The Contact for this Account. If not provided, the main Contact for the Account is taken.
|-
|Field1
|FLDDOCTRANSPORT
|User Defined field
|-
|Field2
|FLDDOCFOLDER
|User Defined field
|-
|Field3
|FLDDOCUMENTPLACE
|User Defined field
|-
|File Path + File name
|FLDDOCDOCUMENTNAME
|The Document path
|-
|Category
|FLDDOCTREEID
|The category record ID should be taken from the database table called TreeTbl which contains the Category tree
|-
| Employee REC ID
| FLDDOCWORKERID
| The worker record ID to be linked to the Document. Must be an active employee. This is an optional parameter. If not passed, the system default will be used.
|-
| Created by User
| FLDDOCCREATEUSER
| Name of external software which created the document
|-
| Last Update: By User
| FLDDOCUPDATEUSER
| Name of external software which updated the document
|}

===Knowledge Base Article Fields===
The table below lists the Knowledge Base Article parameters and behavior:

{| class="wikitable"
|-
! '''Field Name'''
! '''Database Field Name'''
! '''Comment'''
|-
| Record ID
| FLDKBARECID
| The Article record ID. If provided, the existing Article will be updated. Otherwise, this will be added as a new Article.
|-
| Document Date
| FLDKBACREATEDATE
| The date for the Document. This is an optional parameter. If not provided, or if the value is illegal, the current date will be used. Should be passed in date format. e.g. MM/DD/YYYY
|-
| Title
| FLDKBATITLE
|
|-
| Problem
| FLDKBAPROBLEM
|
|-
| Solution
| FLDKBASOLUTION
|
|-
| Status
| FLDKBASTATUS
| Possible values:
*DRAFT = 'D'
*PUBLISHED = 'P'
*OBSOLETE = 'O'
|-
|Category
|FLDKBACATEGORY
|
|-
|Public
|FLDKBAISPUBLIC
|Is the Document public. 
Possible values: 
*'Y' = Yes
*'N' = No
|-
|Created by User
|FLDDOCCREATEUSER
|Name of external software which created the document
|-
|Last Update: By User
|FLDDOCUPDATEUSER
|Name of external software which updated the document
|}

===Error Codes Description===
These error codes are returned when calling the CmtGetDescriptionByStatus function: 
'''1000''' CmtDbEng.dll not found. 
'''1001''' Invalid value for the Data Kind value. 
'''1002''' Invalid DATA buffer received. Make sure you have allocated the buffer correctly and
that you have passed the correct buffer length. 
'''1003''' Invalid MAP buffer received. Make sure you have allocated the buffer correctly and
that you have passed the correct buffer length. 
'''1004''' Invalid REC ID buffer received. Make sure you have allocated the buffer correctly
and that you have passed the correct buffer length. 
'''1005''' Invalid LOG buffer received. Make sure you've allocated the buffer correctly and
that you've passed the correct buffer length. 
'''1006''' Invalid REC ID buffer received. It should be at least 20 characters. 
'''1007''' Invalid external software name received. Specify a unique name that identifies your
software. 
'''1008''' Cannot process the transaction. Make sure to call the INIT procedure at least once
prior to sending transactions for processing. 
'''1009''' Path specified for Commit DB folder not found. 
'''1010''' Path specified for Commit DB folder found, but its contents do not reflect a valid DB
folder. 
'''1011''' The RED ID received for the employee/user was not found in Commit, is invalid or is
related to an inactive employee record. 
'''1012''' Error registering software. 
'''1013''' Software name is missing. Make sure you specify a name that identifies your
software. 
'''1014''' Software name is less than 3 characters long. Make sure you enter a software name
that has 3 to 15 characters. 
'''1015''' Software name is too long. Make sure your software name has 3 to 15 characters. 
'''1100''' Database access error. 

General error codes, returned when calling the functions CmtGetDescriptionByCode: 
'''50000''' The data is not correct for its type. 
'''50001''' The field value has been truncated due to the field length in the database. 
'''50002''' The insert operation Failed because the REC ID already existed in the database. 
'''50003''' Failed to update Record since it is being updated by another user. 
'''50103''' Illegal REC ID. 
'''50104''' REC ID Creation failed. 
'''50105''' Illegal Sub-Contact REC ID. 
'''50106''' Illegal Contract REC ID. 
'''50107''' Illegal Employee REC ID. 
'''50108''' Illegal Ticket REC ID. 
'''50109''' Illegal Account REC ID. 
'''50110''' Illegal data for that Contract. 
'''50111''' This Employee is not active. 
'''50112''' Illegal Document REC ID. 
'''50113''' Illegal linked object REC ID. 
'''50114''' Employee not found. 
'''50115''' Some mandatory fields have no values. 
'''51000''' Illegal kind of Account entity. 
'''51001''' Account Manager not found. 
'''51002''' The REC ID of the Account Manager is illegal. 
'''51003''' Illegal tax code. 
'''51004''' This code does not exist in Commit. 
'''52000''' Illegal kind of event. 
'''52001''' Illegal start time. 
'''52002''' Illegal end time. 
'''52003''' Illegal event date. 
'''52004''' The field Reminder1 has Illegal Value. 
'''52005''' The amount in the field has an illegal value. 
'''52006''' The Field Remider1:Units has Illegal Value. 
'''52007''' The Field Remider2:Active has Illegal Value. 
'''52008''' The Field Remider2:Amount has Illegal Value. 
'''52009''' The Field Remider2:Units has Illegal Value. 
'''52010''' Illegal employee REC ID. 
'''52011''' Error occurred while updating the Task/Appointment employee field. 
'''54000''' Illegal Ticket open date. 
'''54001''' Illegal Ticket close date. 
'''54002''' Illegal Ticket code area. 
'''54004''' Illegal Ticket priority. 
'''54005''' Illegal Ticket status. 
'''54006''' The Ticket Account was not found in the database. 
'''54007''' The Ticket Account Manager was not ound in the database. 
'''54008''' This code does not exist in Commit. 
'''54009''' This code does not exist in Commit. 
'''54010''' This code does not exist in Commit. 
'''54011''' This code does not exist in Commit. 
'''54012''' This code does not exist in Commit. 
'''55000''' Illegal charge date. 
'''55001''' Illegal charge REC ID. 
'''55002''' Illegal start date. 
'''55003''' Illegal start time. 
'''55004''' Illegal amount entered for hours. 
'''55005''' Illegal quantity. 
'''55006''' Illegal price. 
'''55007''' Illegal total. 
'''55008''' Illegal value in the Adjust Amount field. 
'''55009''' Illegal value in the Adjust Percent. 
'''55010''' The Discount/Markup field has an illegal value. 
'''55011''' Illegal value in the Adjust Kind field. 
'''55012''' Illegal bill total. 
'''55013''' You can not create a charge for a suspended item. 
'''55014''' Item was not found in Commit. 
'''55015''' This code does not exist in Commit. 
'''55016''' This code does not exists in Commit. 
'''55017''' This Code does not exist in Commit. 
'''55018''' This Code does not exist in Commit. 
'''55019''' This Code does not exist in Commit. 
'''55020''' This Code does not exist in Commit. 
'''55021''' This Code does not exist in Commit. 
'''56000''' Illegal item code. 
'''56001''' The field that indicates the item group type has an illegal value. 
'''56002''' The field that indicates if the Item is suspended has an illegal value. 
'''56003''' Illegal value of The field that indicate if the item is suspended. 
'''56004''' Mismatch found between the fields price and price source. 
'''56005''' Illegal cost. 
'''56006''' Mismatch found between the fields cost and item group type. 
'''56007''' The field that indicates if the charge is by unit or by hours has an illegal value. 
'''56008''' Illegal value in the Description. 
'''56009''' The field that indicates the item type has an illegal value. 
'''57000''' This Code does not exist in Commit. 
'''58000''' Illegal date time. 
'''58001''' The Description field was not found. 
'''58002''' The field kind was not found. 
'''58003''' The Account member was not found. 
'''59000''' This code does not exists in Commit. 
'''59001''' This Code does not exist in Commit. 
'''59002''' This Code does not exist in Commit. 
'''59003''' This Code does not exist in Commit. 
'''59004''' This Code does not exist in Commit. 
'''59005''' This Code does not exist in Commit. 
'''60000''' Invalid web user record ID number. 
'''60001''' This customer web user is not active. 
'''60002''' This user is not a customer. 

==See Also==
*[[Commit API Developers Guide]]
*[[API Code Samples]]
[[Category:User Manuals]]
[[Category:Integration]]

__NOTOC__

API Reference Manual

2010-02-23T14:20:52Z

Reno: /* Item Fields */

{{usermanualsapidevelopersguide}}
==Intorduction==

Following is a detailed listing of fields per entity which can be added/updated using the API. The API parameters are the same when using the Programming API or the XML API.

The API allows you to add/update the following entities:
*[[#Account Fields|Accounts]]
*[[#Ticket Fields|Tickets]]
*[[#Charge Fields|Charges (and Contract-price Charges)]]
*[[#Item Fields|Items]]
*[[#History Note Fields|History Notes]]
*[[#Asset Fields|Assets]]
*[[#Calendar Fields|Calender]]
*[[#Opportunity Fields|Opportunities]]
*[[#Document Fields|Documents]]
*[[#Knowledge Base Article Fields|Knowledge Base Articles]]

All API functions may return error codes. You can find the possible error codes in:
*[[#Error Codes Description|Error Codes]]

In the following section you will find a detailed listing of the database fields. Each table includes the fields '''Display name''' (as shows in the application), the '''Database Field Name''' (internal database field identifier) and comments.

Note that when using XML formatted messages, the database field name refers to the name to be provided within the XML token. For example, when the field name is FLDSLPQUANTITY, the XML token should look like this:
<FLDSLPQUANTITY>10</FLDSLPQUANTITY>

The following table shows the data kind code when using XML or when using the API functions:

{| class="wikitable"
|-
! '''Application entity'''
! '''Table name'''
! '''Programming Code'''
! '''XML Data Kind Name'''
|-
| Accounts
| Cards
| 10
| ACCOUNT
|-
| Opportunities
| Opps
| 20
| OPPORTUNITY
|-
| Documents
| Docs
| 30
| DOCUMENT
|-
| Charges
| Slips
| 40
| CHARGE
|-
| Appointments/Tasks
| Events
| 50
| APPOINTMENT-OR-TASK
|-
| History Notes
| Notebook
| 60
| HISTORY-NOTE
|-
| Tickets
| Tickets
| 70
| TICKET
|-
| Items
| Items
| 80
| ITEM
|-
| Assets
| Assets
| 90
| ASSET
|-
| Knowledge Base
| KBArticles
| 100
| KBARTICLE
|}
You can find examples of adding and updating records in the database by using the database field in the [[API Code Samples]] section.

===Account Fields===
The following table lists the most important parameters for adding/updating Account
records.
Note slight differences when adding a main account vs. adding a secondary contact.

{| class="wikitable"
|-
! '''Field Name'''
! '''Database Field Name'''
! '''Comment'''
|-
| Account REC ID
| FLDCRDRECID
|The Account record ID (20 chars). The Account Rec ID can be taken from:
#Account Notes tab, at the bottom, rightclick the RecID field and use Copy. e.g. CRDVQYSOD1B4U4HZIQJJ
#Using ODBC to pull information from the database.
#From the Email Response when adding new Account with the API.
|-
| Account Manager
| FLDCRDASSIGNCARDID
| This field has two roles:
#When adding a main Account: The account manager should contain the ID of the Employee who is the account manager.
#When adding a secondary contact: 
This field should contain the ID of the main Account to which the secondary contacted is
added.
|-
|Company name
|FLDCRDCOMPANY
|
|-
|Contact: First & Last Name
|FLDCRDCONTACT
|
|-
| Assistant
| FLDCRDASSISTANT
|
|-
|Contract
|FLDCRDBCRECID
|The default Contract for this Account (not required)
|-
|Account Number
|FLDCRDCARDID2
|
|-
|ID
|FLDCRDCARDID3
|
|-
|Popup Message
|FLDCRDCARDMESSAGE
|
|-
| Address: Line1
| FLDCRDADDRESS1
|
|-
| Address: Line2
| FLDCRDADDRESS2
|
|-
| Address: Line3
| FLDCRDADDRESS3
|
|-
|Address: City
|FLDCRDCITY
|
|-
|Address: State
|FLDCRDCOUNTRY
|
|-
|Address: Country
|FLDCRDSTATE
|
|-
|Address: Zip
|FLDCRDZIP
|
|-
|Creation Date
|FLDCRDCREATEDATE
|Any date format, such as DD/MM/YYYY
|-
|Created by User
|FLDCRDCREATEUSERID
|Foreign Software Name which created the account
|-
|Dear
|FLDCRDDEAR
|
|-
|Department
|FLDCRDDEPARTMENT
|
|-
|Documents Store Directory
|FLDCRDDOCSFOLDER
|
|-
|E-Mail Address 1
|FLDCRDEMAIL1
|
|-
|E-Mail Address 2
|FLDCRDEMAIL2
|
|-
|Account Type
|FLDCRDENTITYKIND
|When adding a Main Account = 1 When adding a secondary contact = 5
|-
|Fax Number
|FLDCRDFAX1
|
|-
|Fax Number Extension
|FLDCRDFAXDESC1
|
|-
|File as
|FLDCRDFULLNAME
|
|-
|Type
|FLDCRDKIND
|
|-
|Last Name
|FLDCRDLASTNAME
|
|-
|Notes
|FLDCRDNOTES
|
|-
|Field
|FLDCRDPERSONID
|
|-
|Phone 1 Ext.
|FLDCRDPHNDESC1
|
|-
|Phone 2 Ext.
|FLDCRDPHNDESC2
|
|-
|Phone 3 Ext.
|FLDCRDPHNDESC3
|
|-
|Phone 4 Ext.
|FLDCRDPHNDESC4
|
|-
|Phone 1
|FLDCRDPHONE1
|
|-
|Phone 2
|FLDCRDPHONE2
|
|-
|Phone 3
|FLDCRDPHONE3
|
|-
|Phone 4
|FLDCRDPHONE4
|
|-
|Region
|FLDCRDREGIONCODE
|
|-
|Popup Message: Display Indication
|FLDCRDSHOWMESSAGE
|
|-
|Sub-Contact Code
|FLDCRDSUBCODE
|
|-
|Salutation
|FLDCRDSUFFIX
|
|-
|Tax1
|FLDCRDTAXCODE1
|
|-
|Tax2
|FLDCRDTAXCODE2
|
|-
|Notes
|FLDCRDNOTES
|
|-
|Title
|FLDCRDTITLE
|
|-
|Last Updated by
|FLDCRDUPDATEUSERID
|When performing updates on existing Account - pass the Foreign Software Name which performs the update.
|-
|Web Address 1
|FLDCRDURL1
|
|-
|Web Address 2
|FLDCRDURL2
|
|-
|Status
|FLDCRDUSER1
|
|-
|Field1
|FLDCRDUSER2
|
|-
|Field2
|FLDCRDUSER3
|
|-
|Field3
|FLDCRDUSER4
|
|-
|Field4
|FLDCRDUSER5
|
|}

===Ticket Fields===

The table below lists the most important Ticket parameters and behavior:

{| class="wikitable"
|-
! '''Field Name'''
! '''Database Field Name'''
! '''Comment'''
|-
| Account REC ID
| FLDTKTCARDID
|The Account record ID (20 chars). The Account Rec ID can be taken from:
#Account Notes tab, at the bottom by rightclicking the REC ID field and selecting Copy
#ODBC to pull information from the database
#The automated email response when adding a cnew Account with the API
|-
| Contact REC ID
| FLDTKTCONTACTID
|The Contact for this Account. If not provided, the main Contact for the Account is taken.
|-
| Contract REC ID
| FLDTKTBCRECID
|The Contract ID. If not supplied, will be taken from the Account's default contract.
|-
| Emp. REC ID
| FLDTKTWORKERID
|The worker ID to be linked to the Ticket. Must be an active employee. This is an optional parameter. If not passed, the system default will be used.
|-
| Priority
| FLDTKTPRIORITY
| The ticket priority. If not passed in the transaction, the default value for new Tickets will be used.
Immediate = 10 High = 20 Normal = 30 Low = 40 Not Applicable= 50
|-
| Ticket Number
| FLDTKTTICKETNO
| The Ticket number. If passed, must be an existing Ticket, and this will update the Ticket with the details in the transaction.
|-
|Description
|FLDTKTPROBLEM
|This is the Ticket Description. This is a mandatory field, which must contain text.
|-
|Ticket Type
|FLDTKTKIND
|Ticket Type (optional). The Ticket Type string should be passed. If not provided, default is used.
|-
|Source
|FLDTKTSOURCE
|
|-
|Estimated Duration Time
|FLDTKTSCHEDLENESTIM
|Estimated duration time for the Ticket in minutes.
|-
|Show Ticket in Dispatcher
|FLDTKTFORDISPATCH
|Possible values: Yes/No
|-
|Status
|FLDTKTSTATUS
|The Ticket Status (optional). 
Possible values: 
New = 100 
Pending = 200 
Scheduled = 300 
In-House Service = 400 
On-Site Service = 500 
Laboratory Service = 600 
Hold = 700 
Other = 800 
Canceled = 900 
Completed = 1000
|-
|Created by User
|FLDTKTCREATEUSER
|Should contain the external software name which created the Ticket
|-
|Due Date
|FLDTKTDUEDATETIME
|Due date for the Ticket. Should be passed in date format. e.g. MM/DD/YYYY
|-
|Resolution
|FLDTKTSOLUTION
|Ticket resolution text
|}

===Charge Fields===
The table below lists the most important Charge parameters and behavior.

Contract-price Charges have some special characteristics (see comments marked by * in
the table below):

{| class="wikitable"
|-
! '''Field Name'''
! '''Database Field Name'''
! '''Comment'''
|-
| Record ID
| FLDSLPRECID
|The Charge record ID. If provided, the existing Charge will be updated. Otherwise, this will be
added as a new Charge.
|-
| Charge Source
| FLDSLPSOURCERECID
|The Charge source is the entity for which the charge is created. 
Possible values:
*Linked Contract RecID (for Contract-price Charges). Cannot be the "System Global Contract".
**Passing the Contract RecID indicates that this is a Contract-price charge.
*Entity RecID from which the charge is created (for example when creating a charge from an Appointment or Task).
|-
| Account REC ID
| FLDSLPCARDID
|The Account record ID (20 chars). The Account REC ID can be taken from:
#Account Notes tab, at the bottom by rightclicking the REC ID field and selecting Copy
#ODBC to pull information from the database
#The automated email response when adding a new Account with the API
|-
| Employee REC ID
| FLDSLPWORKERID
| The worker record ID to be linked to the Charge. Must be an active employee. This is an optional parameter. If not passed, the system default will be used.
|-
| Charged Item
| FLDSLPITEMID
| The Item Record ID to be linked to the Charge. This is a mandatory field.
*For Contract-price Charge can be only Fixed-Price, Unit-based Item.
|-
| Contract REC ID
| FLDSLPBCRECID
| The contract record ID (must be a Contract of the Account)
|-
|Ticket REC ID
|FLDSLPTICKETID
|The Ticket ID to be linked to the Charge.
*Not relevant for Contract-price Charge
|-
|Date
|FLDSLPSLIPDATE
|The date for the Charge. This is an optional parameter. If not provided, the current date will
be used. Should be passed in date format. e.g. MM/DD/YYYY
|-
|Description
|FLDSLPDESC
|The Charge Description. If not provided, will be taken from the Item's description.
|-
|Units/Hours
|FLDSLPQUANTITY
|This is the quantity of hours/units
|-
|Adjust Amount
|FLDSLPADJUSTAMOUNT
|Discount/Markup amount. Positive number means Markup, negative number means Discount.
|-
|Adjust Percent
|FLDSLPADJUSTPERCENT
|Discount/Markup in percentage, must be between (-100) - 100. Positive number means Markup, negative number means Discount.
|-
|From Time
|FLDSLPSTARTTIME
|From time for labor Charges e.g. 12:06
*Not relevant for Contract-price Charge
|-
|To Time
|FLDSLPENDTIME
|From time for labor Charges e.g. 14:50
* Not relevant for Contract-price Charge
|-
|Price/Rate
|FLDSLPPRICE
|If not provided, the price is taken from the Item.
|-
| Billable
| FLDSLPBILLKIND
| B - Billable 
N - Not Billable 
If not provided, will be set according to the Contract type.
|-
| Billed
| FLDSLPSTAGE
| D - Draft
B - Billed
|-
| Field1
| FLDSLPUSER1
| User defined field
|-
| Create User
| FLDSLPCREATEUSER
| External software name which created the Charge
|}

===Item Fields===

The table below lists the most important Item parameters and behavior:

{| class="wikitable"
|-
! '''Field Name'''
! '''Database Field Name'''
! '''Comment'''
|-
| Record ID
| FLDITMRECID
|The Item record ID. If provided, the existing item will be updated. Otherwise, this will be added as a new item.
|-
| Item Group
| FLDITMITEMTYPEGROUP
|The Item Group to be linked to the Charge. This is a mandatory field: 
F - Labor (Fee) 
X - Expense 
P - Part
|-
| Item Code
| FLDITMITEMNO
|The item code is a mandatory field
|-
| Item Name
| FLDITMNAME
| The item name is a mandatory field
|-
| Price Source
| FLDITMPRICESOURCE
| F - Fixed Price 
W - by Employee Rate
|-
| Price per Hour/Unit
| FLDITMUNITISHOUR
| This field indicated whether the price is unitbased or hours-based. 
Y - by Hours 
N - by Units 
This is an optional field, depending on the Item Group. For example, if the item group is Labor, and Price Source is By Employee, the value will always be by hours
|-
|Price
|FLDITMUNITPRICE
|Must be a valid numeric value
|-
|Cost
|FLDITMSTANDARDCOST
|The date for the Charge. This is an optional parameter. If not provided, the current date will
be used. Should be passed in date format. e.g. MM/DD/YYYY
|-
|Taxes
|FLDITMTAXCODE1 
FLDITMTAXCODE2 
FLDITMTAXCODE3
|You can pass up to 3 different tax codes.
|-
|Description by Name
|FLDITMDESCBYNAME
|Y - take the description from the name field 
N - take the description from the Description field
|-
|Description
|FLDITMDESC
|If not provided, the description is taken from the name.
|-
|Suspend
|FLDITMSUSPENDED
|Indicated whether this item is currently suspended: 
Y - yes 
N - no
|-
|Notes
|FLDITMNOTES
|
|-
|Field1
|FLDSLPUSER1
|User defined field
|-
|Create User
|FLDSLPCREATEUSER
|External software name which created the Charge
|-
| Created by User
| FLDTKTCREATEUSER
| Should contain the external software name which created the Ticket
|}

===History Note Fields===
The table below lists the most important History Note parameters and behavior:

{| class="wikitable"
|-
! '''Field Name'''
! '''Database Field Name'''
! '''Comment'''
|-
| Record ID
| FLDHISRECID
|The History Note record ID. If provided, the existing History Note will be updated. otherwise, this will be added as a new History Note.
|-
| Date
| FLDHISNOTEDATETIME
|Any date format, such as DD/MM/YYYY
|-
| Description
| FLDHISDESCRIPTION
| The Description text
|-
| Opportunity/Ticket/Contract
| FLDHISLINKRECID
| Link to Opportunity or Ticket or Contract
|-
| Field
| FLDHISUSER1
| User defined field
|-
| About
| FLDHISKIND
| Optional field
|-
|Employee
|FLDHISWORKERID
|The worker ID to be linked to the Ticket. Must be an active employee. This is an optional parameter. If not passed, the system default will be used.
|-
|Account
|FLDHISCARDID
|The Account record ID (20 chars). The Account Rec ID can be taken from:
#Account Notes tab, at the bottom, right-click the REC ID field and use Copy. e.g. CRDVQYSOD1B4U4HZIQJJ
#Using ODBC to pull information from the database
#From the Email Response when adding new Account with the API
|-
|Contact
|FLDHISCONTACTID
|The Contact for this Account. If not provided, the main Contact for the Account is taken.
|-
|Document
|FLDHISDOCID
|Linked Document ID, can be taken from the Document Properties window (right-click RecID and use Copy), or using the ODBC to pull information from the database.
|-
|Created by User
|FLDHISCREATEUSER
|Name of the external software which created this History Note
|}

===Asset Fields===
The table below lists the most important Asset parameters and behavior:

{| class="wikitable"
|-
! '''Field Name'''
! '''Database Field Name'''
! '''Comment'''
|-
| Asset Code
| FLDASTASSETCODE
|If an existing Asset Code is provided, then existing Asset is updated. Otherwise a new Asset is added.
|-
| Asset Type
| FLDASTASSETTYPE
|The Type field is mandatory: 
Hardware = H 
Software = S 
Other = T
|-
| Asset Name
| FLDASTNAME
|
|-
| Status
| FLDASTSTATUS
| Mandatory field. 
Active = A 
Not Active = N 
If not provided, default Active is used.
|-
| Record ID
| FLDASTRECID
| If provided, must exist in the database. Ignored if empty
|-
| Serial No.
| FLDASTSERIALNO
|
|-
|Account
|FLDASTACCRECID
|The Account which is linked to the Asset
|-
|Contact
|FLDASTCONTACTRECID
|The Contact for this Account. If not provided, the main Contact for the Account is taken.
|-
|Created by user
|FLDASTCREATEUSER
|Name of external software which created this Asset
|-
|Purchase Date
|FLDASTCUSTPURDATE
|Any date format, such as DD/MM/YYYY
|-
|Purchased From Us
|FLDASTCUSTPURFROMUS
|Possible values: Y/N. 
If not provided, default value Y is used.
|-
| Purchase Invoice #
| FLDASTCUSTPUROURINV
|
|-
| Customer PO
| FLDASTCUSTPURPO
|
|-
| Purchase Price
| FLDASTCUSTPURPRICE
|
|-
| Delivered Date
| FLDASTDELIVEDATE
|
|-
| Description
| FLDASTDESC
|
|-
| Installed By
| FLDASTINSTALBY
|
|-
| Installed Date
| FLDASTINSTALDATE
|
|-
| License Codes
| FLDASTLICENSECODE
|
|-
| License Keys
| FLDASTLICENSEKEY
|
|-
| License Notes
| FLDASTLICENSENOTES
|
|-
| Location
| FLDASTLOCATION
|
|-
| Manufacturer
| FLDASTMANUFACTURER
|
|-
| Mnf Serial No.
| FLDASTMNFSERIALNO
|
|-
| Model
| FLDASTMODEL
|
|-
| Notes
| FLDASTNOTES
|
|-
| Quantity
| FLDASTQUANTITY
| If not provided, default value of 1 is used.
|-
| Last Update By
| FLDASTUPDATEUSER
| Name of externals software which performed the update
|-
| Field1
| FLDASTUSER1
| User defined field
|-
| Field2
| FLDASTUSER2
| User defined field
|-
| Field3
| FLDASTUSER3
| User defined field
|-
| Field4
| FLDASTUSER4
| User defined field
|-
| Field5
| FLDASTUSER5
| User defined field
|-
| Date1
| FLDASTUSERDATE1
| User defined field
|-
| Number1
| FLDASTUSERNUMBER1
| User defined field
|-
| Vendor Purchased Date
| FLDASTVENDORDATEPURC
|
|-
| Vendor Invoice #
| FLDASTVENDORINVNO
|
|-
| Vendor PO
| FLDASTVENDOROURPO
|
|-
| Vendor Price
| FLDASTVENDORPRICE
|
|-
| Vendor
| FLDASTVENDORRECID
|
|-
| Vendor Serial No.
| FLDASTVENDORSERNO
|
|-
| Vendor Warranty Exp. Date
| FLDASTVENDORWARREXP
| Any date format, such as DD/MM/YYYY
|-
| Version
| FLDASTVERSION
|
|-
| Warranty/License Exp.
| FLDASTWARREXPDATE
| Any date format, such as DD/MM/YYYY
|-
| Date
|
|
|}

===Calendar Fields===
The table below lists the most important Calendar parameters and behavior:

{| class="wikitable"
|-
! '''Field Name'''
! '''Database Field Name'''
! '''Comment'''
|-
| Record ID
| FLDEVTRECID
|The Appointment/Task record ID. If provided, the existing entity will be updated. Otherwise, this
will be added as a new Appointment/Task.
|-
| Event Type
| FLDEVTWRITETOID
|The Event type is a mandatory field. 
Appointment = 1 
Task = 2
|-
| Employee
| FLDEVTWORKERID
| The Task/Appointment owner (for private events)
|-
| Private: User
| FLDEVTPRIVATEID
| Possible values: Y/N 
If an Employee was set, this field must be Y
|-
| Account
| FLDEVTCARDID
| The Account record ID (20 chars). The Account REC ID can be taken from:
#Account Notes tab, at the bottom by rightclicking
the REC ID field and selecting Copy
#ODBC to pull information from the database
#The automated email response when adding a
new Account with the API
|-
| Contact
| FLDEVTCONTACTID
| The Contact for this Account. If not provided, the main Contact for the Account is taken.
|-
|Document
|FLDEVTDOCID
|Linked Document ID, can be taken from the Document Properties window (right-click RecID and use Copy), or using the ODBC to pull information from the database.
|-
|Done Indication
|FLDEVTDONE
|Possible values: Y/N
|-
|Date
|FLDEVTEVENTDATE
|The Appointment/Task date is a mandatory field of Any date format, such as DD/MM/YYYY. If not
provided, the current date will be used.
|-
|Description
|FLDEVTFREETEXT
|
|-
|Time: Start
|FLDEVTFROMTIME
|Mandatory field
|-
| Time: End
| FLDEVTTOTIME
| Relevant only for Appointments. If this parameter is not provided, 30 min. interval from Start Time is used.
|-
| Opportunity/Ticket
| FLDEVTLINKRECID
| Linked Ticket/Opportunity/Contract/Asset
|-
| Field1
| FLDEVTFAMILY
| User Defined field
|-
| Field2
| FLDEVTACTION
| User Defined field
|-
| Field3
| FLDEVTPLACE
| User Defined field
|-
| Field4
| FLDEVTPLACE1
| User Defined field
|-
| Field5
| FLDEVTPLACE2
| User Defined field
|-
| Created by User
| FLDEVTCREATEUSERID
| Name of external software which created the event
|-
| Last Update: By User
| FLDEVTUPDATEUSER
| Name of external software which updated the
event
|}

===Opportunity Fields===
The table below lists the most important Opportunity parameters and behavior:

{| class="wikitable"
|-
! '''Field Name'''
! '''Database Field Name'''
! '''Comment'''
|-
| Record ID
| FLDOPPRECID
| The Opportunity record ID. If provided, the existing Opportunity will be updated. Otherwise, this will be added as a new Opportunity.
|-
| Opportunity Name
| FLDOPPNAME
| Mandatory field.
|-
| Opportunity ID
| FLDOPPUSERID
| Optional (Oppty ID)
|-
| Account
| FLDOPPCARDID
| The Account record ID (20 chars). The Account REC ID can be taken from:
#Account Notes tab, at the bottom by right-clicking the REC ID field and selecting Copy
#ODBC to pull information from the database
#The automated email response when adding a new Account with the API
|-
| Contact
| FLDEVTCONTACTID
| The Contact for this Account. If not provided, the main Contact for the Account is taken.
|-
| Source
| FLDOPPSOURCE
|
|-
|Document
|FLDEVTDOCID
|Linked Document ID, can be taken from the Document Properties window (right-click RecID and use Copy), or using the ODBC to pull information from the database.
|-
|Done Indication
|FLDEVTDONE
|Possible values: Y/N
|-
|Close Date
|FLDOPPCLOSEDATE
|
|-
|Manager
|FLDOPPWORKERID
|The Manager's REC ID
|-
|Open Date
|FLDOPPOPENDATE
|
|-
| Close By Date
| FLDOPPESTDATE
| Opportunity must be closed by this date
|-
| Amount
| FLDOPPAMOUNT
|
|-
| Probability %
| FLDOPPPROBABILITY
|
|-
| Stage
| FLDOPPSTAGE
|
|-
| Status
| FLDOPPSTATUS
|
|-
| Closing Amount
| FLDOPPCLOSEAMOUNT
|
|-
| Description
| FLDOPPDESCRIPTION
|
|-
| Opportunity Type
| FLDOPPKIND
|
|-
| Opportunity Reason
| FLDOPPREASON
|
|-
| Note
| FLDOPPNOTES
|
|-
| Territory
| FLDOPPREGION
|
|-
| Field1
| FLDEVTFAMILY
| User Defined field
|-
| Field2
| FLDEVTACTION
| User Defined field
|-
| Field3
| FLDEVTPLACE
| User Defined field
|-
| Created by User
| FLDEVTCREATEUSERID
| Name of external software which created the event
|-
| Last Update: By User
| FLDEVTUPDATEUSER
| Name of external software which updated the event
|}

===Document Fields===
The table below lists the Document parameters and behavior:

{| class="wikitable"
|-
! '''Field Name'''
! '''Database Field Name'''
! '''Comment'''
|-
| Record ID
| FLDDOCRECID
| The Document record ID. If provided, the existing Document will be updated. Otherwise, this will be added as a new Document.
|-
| Document Date
| FLDDOCDOCDATE
| The date for the Document. This is an optional parameter. If not provided, or if the value is illegal, the current date will be used. Should be passed in date format. e.g. MM/DD/YYYY
|-
| Subject
| FLDOPPUSERID
|
|-
| Linked Record
| FLDDOCLINKRECID
| The RECID of a linked object. Each Document can be linked to one of the following objects:
*Ticket
*Contract
*Opportunity
*Knowledge Base Article
*Asset
The Record ID (20 chars) can be taken from:
#Object's Notes tab, at the bottom by right-clicking the REC ID field and selecting Copy
#ODBC to pull information from the database
#The automated email response when adding a new object with the API.
|-
| Account Rec ID
| FLDDOCCARDID
| The Account record ID (20 chars). The Account REC ID can be taken from:
#Account Notes tab, at the bottom by right-clicking the REC ID field and selecting Copy
#ODBC to pull information from the database
#The automated email response when adding a new Account with the API
|-
| Contact REC ID
| FLDDOCCONTACTID
| The Contact for this Account. If not provided, the main Contact for the Account is taken.
|-
|Field1
|FLDDOCTRANSPORT
|User Defined field
|-
|Field2
|FLDDOCFOLDER
|User Defined field
|-
|Field3
|FLDDOCUMENTPLACE
|User Defined field
|-
|File Path + File name
|FLDDOCDOCUMENTNAME
|The Document path
|-
|Category
|FLDDOCTREEID
|The category record ID should be taken from the database table called TreeTbl which contains the Category tree
|-
| Employee REC ID
| FLDDOCWORKERID
| The worker record ID to be linked to the Document. Must be an active employee. This is an optional parameter. If not passed, the system default will be used.
|-
| Created by User
| FLDDOCCREATEUSER
| Name of external software which created the document
|-
| Last Update: By User
| FLDDOCUPDATEUSER
| Name of external software which updated the document
|}

===Knowledge Base Article Fields===
The table below lists the Knowledge Base Article parameters and behavior:

{| class="wikitable"
|-
! '''Field Name'''
! '''Database Field Name'''
! '''Comment'''
|-
| Record ID
| FLDKBARECID
| The Article record ID. If provided, the existing Article will be updated. Otherwise, this will be added as a new Article.
|-
| Document Date
| FLDKBACREATEDATE
| The date for the Document. This is an optional parameter. If not provided, or if the value is illegal, the current date will be used. Should be passed in date format. e.g. MM/DD/YYYY
|-
| Title
| FLDKBATITLE
|
|-
| Problem
| FLDKBAPROBLEM
|
|-
| Solution
| FLDKBASOLUTION
|
|-
| Status
| FLDKBASTATUS
| Possible values:
*DRAFT = 'D'
*PUBLISHED = 'P'
*OBSOLETE = 'O'
|-
|Category
|FLDKBACATEGORY
|
|-
|Public
|FLDKBAISPUBLIC
|Is the Document public. 
Possible values: 
*'Y' = Yes
*'N' = No
|-
|Created by User
|FLDDOCCREATEUSER
|Name of external software which created the document
|-
|Last Update: By User
|FLDDOCUPDATEUSER
|Name of external software which updated the document
|}

===Error Codes Description===
These error codes are returned when calling the CmtGetDescriptionByStatus function: 
'''1000''' CmtDbEng.dll not found. 
'''1001''' Invalid value for the Data Kind value. 
'''1002''' Invalid DATA buffer received. Make sure you have allocated the buffer correctly and
that you have passed the correct buffer length. 
'''1003''' Invalid MAP buffer received. Make sure you have allocated the buffer correctly and
that you have passed the correct buffer length. 
'''1004''' Invalid REC ID buffer received. Make sure you have allocated the buffer correctly
and that you have passed the correct buffer length. 
'''1005''' Invalid LOG buffer received. Make sure you've allocated the buffer correctly and
that you've passed the correct buffer length. 
'''1006''' Invalid REC ID buffer received. It should be at least 20 characters. 
'''1007''' Invalid external software name received. Specify a unique name that identifies your
software. 
'''1008''' Cannot process the transaction. Make sure to call the INIT procedure at least once
prior to sending transactions for processing. 
'''1009''' Path specified for Commit DB folder not found. 
'''1010''' Path specified for Commit DB folder found, but its contents do not reflect a valid DB
folder. 
'''1011''' The RED ID received for the employee/user was not found in Commit, is invalid or is
related to an inactive employee record. 
'''1012''' Error registering software. 
'''1013''' Software name is missing. Make sure you specify a name that identifies your
software. 
'''1014''' Software name is less than 3 characters long. Make sure you enter a software name
that has 3 to 15 characters. 
'''1015''' Software name is too long. Make sure your software name has 3 to 15 characters. 
'''1100''' Database access error. 

General error codes, returned when calling the functions CmtGetDescriptionByCode: 
'''50000''' The data is not correct for its type. 
'''50001''' The field value has been truncated due to the field length in the database. 
'''50002''' The insert operation Failed because the REC ID already existed in the database. 
'''50003''' Failed to update Record since it is being updated by another user. 
'''50103''' Illegal REC ID. 
'''50104''' REC ID Creation failed. 
'''50105''' Illegal Sub-Contact REC ID. 
'''50106''' Illegal Contract REC ID. 
'''50107''' Illegal Employee REC ID. 
'''50108''' Illegal Ticket REC ID. 
'''50109''' Illegal Account REC ID. 
'''50110''' Illegal data for that Contract. 
'''50111''' This Employee is not active. 
'''50112''' Illegal Document REC ID. 
'''50113''' Illegal linked object REC ID. 
'''50114''' Employee not found. 
'''50115''' Some mandatory fields have no values. 
'''51000''' Illegal kind of Account entity. 
'''51001''' Account Manager not found. 
'''51002''' The REC ID of the Account Manager is illegal. 
'''51003''' Illegal tax code. 
'''51004''' This code does not exist in Commit. 
'''52000''' Illegal kind of event. 
'''52001''' Illegal start time. 
'''52002''' Illegal end time. 
'''52003''' Illegal event date. 
'''52004''' The field Reminder1 has Illegal Value. 
'''52005''' The amount in the field has an illegal value. 
'''52006''' The Field Remider1:Units has Illegal Value. 
'''52007''' The Field Remider2:Active has Illegal Value. 
'''52008''' The Field Remider2:Amount has Illegal Value. 
'''52009''' The Field Remider2:Units has Illegal Value. 
'''52010''' Illegal employee REC ID. 
'''52011''' Error occurred while updating the Task/Appointment employee field. 
'''54000''' Illegal Ticket open date. 
'''54001''' Illegal Ticket close date. 
'''54002''' Illegal Ticket code area. 
'''54004''' Illegal Ticket priority. 
'''54005''' Illegal Ticket status. 
'''54006''' The Ticket Account was not found in the database. 
'''54007''' The Ticket Account Manager was not ound in the database. 
'''54008''' This code does not exist in Commit. 
'''54009''' This code does not exist in Commit. 
'''54010''' This code does not exist in Commit. 
'''54011''' This code does not exist in Commit. 
'''54012''' This code does not exist in Commit. 
'''55000''' Illegal charge date. 
'''55001''' Illegal charge REC ID. 
'''55002''' Illegal start date. 
'''55003''' Illegal start time. 
'''55004''' Illegal amount entered for hours. 
'''55005''' Illegal quantity. 
'''55006''' Illegal price. 
'''55007''' Illegal total. 
'''55008''' Illegal value in the Adjust Amount field. 
'''55009''' Illegal value in the Adjust Percent. 
'''55010''' The Discount/Markup field has an illegal value. 
'''55011''' Illegal value in the Adjust Kind field. 
'''55012''' Illegal bill total. 
'''55013''' You can not create a charge for a suspended item. 
'''55014''' Item was not found in Commit. 
'''55015''' This code does not exist in Commit. 
'''55016''' This code does not exists in Commit. 
'''55017''' This Code does not exist in Commit. 
'''55018''' This Code does not exist in Commit. 
'''55019''' This Code does not exist in Commit. 
'''55020''' This Code does not exist in Commit. 
'''55021''' This Code does not exist in Commit. 
'''56000''' Illegal item code. 
'''56001''' The field that indicates the item group type has an illegal value. 
'''56002''' The field that indicates if the Item is suspended has an illegal value. 
'''56003''' Illegal value of The field that indicate if the item is suspended. 
'''56004''' Mismatch found between the fields price and price source. 
'''56005''' Illegal cost. 
'''56006''' Mismatch found between the fields cost and item group type. 
'''56007''' The field that indicates if the charge is by unit or by hours has an illegal value. 
'''56008''' Illegal value in the Description. 
'''56009''' The field that indicates the item type has an illegal value. 
'''57000''' This Code does not exist in Commit. 
'''58000''' Illegal date time. 
'''58001''' The Description field was not found. 
'''58002''' The field kind was not found. 
'''58003''' The Account member was not found. 
'''59000''' This code does not exists in Commit. 
'''59001''' This Code does not exist in Commit. 
'''59002''' This Code does not exist in Commit. 
'''59003''' This Code does not exist in Commit. 
'''59004''' This Code does not exist in Commit. 
'''59005''' This Code does not exist in Commit. 
'''60000''' Invalid web user record ID number. 
'''60001''' This customer web user is not active. 
'''60002''' This user is not a customer. 

==See Also==
*[[Commit API Developers Guide]]
*[[API Code Samples]]
[[Category:User Manuals]]
[[Category:Integration]]

__NOTOC__

API Reference Manual

2010-02-23T14:19:20Z

Reno: /* Account Fields */

{{usermanualsapidevelopersguide}}
==Intorduction==

Following is a detailed listing of fields per entity which can be added/updated using the API. The API parameters are the same when using the Programming API or the XML API.

The API allows you to add/update the following entities:
*[[#Account Fields|Accounts]]
*[[#Ticket Fields|Tickets]]
*[[#Charge Fields|Charges (and Contract-price Charges)]]
*[[#Item Fields|Items]]
*[[#History Note Fields|History Notes]]
*[[#Asset Fields|Assets]]
*[[#Calendar Fields|Calender]]
*[[#Opportunity Fields|Opportunities]]
*[[#Document Fields|Documents]]
*[[#Knowledge Base Article Fields|Knowledge Base Articles]]

All API functions may return error codes. You can find the possible error codes in:
*[[#Error Codes Description|Error Codes]]

In the following section you will find a detailed listing of the database fields. Each table includes the fields '''Display name''' (as shows in the application), the '''Database Field Name''' (internal database field identifier) and comments.

Note that when using XML formatted messages, the database field name refers to the name to be provided within the XML token. For example, when the field name is FLDSLPQUANTITY, the XML token should look like this:
<FLDSLPQUANTITY>10</FLDSLPQUANTITY>

The following table shows the data kind code when using XML or when using the API functions:

{| class="wikitable"
|-
! '''Application entity'''
! '''Table name'''
! '''Programming Code'''
! '''XML Data Kind Name'''
|-
| Accounts
| Cards
| 10
| ACCOUNT
|-
| Opportunities
| Opps
| 20
| OPPORTUNITY
|-
| Documents
| Docs
| 30
| DOCUMENT
|-
| Charges
| Slips
| 40
| CHARGE
|-
| Appointments/Tasks
| Events
| 50
| APPOINTMENT-OR-TASK
|-
| History Notes
| Notebook
| 60
| HISTORY-NOTE
|-
| Tickets
| Tickets
| 70
| TICKET
|-
| Items
| Items
| 80
| ITEM
|-
| Assets
| Assets
| 90
| ASSET
|-
| Knowledge Base
| KBArticles
| 100
| KBARTICLE
|}
You can find examples of adding and updating records in the database by using the database field in the [[API Code Samples]] section.

===Account Fields===
The following table lists the most important parameters for adding/updating Account
records.
Note slight differences when adding a main account vs. adding a secondary contact.

{| class="wikitable"
|-
! '''Field Name'''
! '''Database Field Name'''
! '''Comment'''
|-
| Account REC ID
| FLDCRDRECID
|The Account record ID (20 chars). The Account Rec ID can be taken from:
#Account Notes tab, at the bottom, rightclick the RecID field and use Copy. e.g. CRDVQYSOD1B4U4HZIQJJ
#Using ODBC to pull information from the database.
#From the Email Response when adding new Account with the API.
|-
| Account Manager
| FLDCRDASSIGNCARDID
| This field has two roles:
#When adding a main Account: The account manager should contain the ID of the Employee who is the account manager.
#When adding a secondary contact: 
This field should contain the ID of the main Account to which the secondary contacted is
added.
|-
|Company name
|FLDCRDCOMPANY
|
|-
|Contact: First & Last Name
|FLDCRDCONTACT
|
|-
| Assistant
| FLDCRDASSISTANT
|
|-
|Contract
|FLDCRDBCRECID
|The default Contract for this Account (not required)
|-
|Account Number
|FLDCRDCARDID2
|
|-
|ID
|FLDCRDCARDID3
|
|-
|Popup Message
|FLDCRDCARDMESSAGE
|
|-
| Address: Line1
| FLDCRDADDRESS1
|
|-
| Address: Line2
| FLDCRDADDRESS2
|
|-
| Address: Line3
| FLDCRDADDRESS3
|
|-
|Address: City
|FLDCRDCITY
|
|-
|Address: State
|FLDCRDCOUNTRY
|
|-
|Address: Country
|FLDCRDSTATE
|
|-
|Address: Zip
|FLDCRDZIP
|
|-
|Creation Date
|FLDCRDCREATEDATE
|Any date format, such as DD/MM/YYYY
|-
|Created by User
|FLDCRDCREATEUSERID
|Foreign Software Name which created the account
|-
|Dear
|FLDCRDDEAR
|
|-
|Department
|FLDCRDDEPARTMENT
|
|-
|Documents Store Directory
|FLDCRDDOCSFOLDER
|
|-
|E-Mail Address 1
|FLDCRDEMAIL1
|
|-
|E-Mail Address 2
|FLDCRDEMAIL2
|
|-
|Account Type
|FLDCRDENTITYKIND
|When adding a Main Account = 1 When adding a secondary contact = 5
|-
|Fax Number
|FLDCRDFAX1
|
|-
|Fax Number Extension
|FLDCRDFAXDESC1
|
|-
|File as
|FLDCRDFULLNAME
|
|-
|Type
|FLDCRDKIND
|
|-
|Last Name
|FLDCRDLASTNAME
|
|-
|Notes
|FLDCRDNOTES
|
|-
|Field
|FLDCRDPERSONID
|
|-
|Phone 1 Ext.
|FLDCRDPHNDESC1
|
|-
|Phone 2 Ext.
|FLDCRDPHNDESC2
|
|-
|Phone 3 Ext.
|FLDCRDPHNDESC3
|
|-
|Phone 4 Ext.
|FLDCRDPHNDESC4
|
|-
|Phone 1
|FLDCRDPHONE1
|
|-
|Phone 2
|FLDCRDPHONE2
|
|-
|Phone 3
|FLDCRDPHONE3
|
|-
|Phone 4
|FLDCRDPHONE4
|
|-
|Region
|FLDCRDREGIONCODE
|
|-
|Popup Message: Display Indication
|FLDCRDSHOWMESSAGE
|
|-
|Sub-Contact Code
|FLDCRDSUBCODE
|
|-
|Salutation
|FLDCRDSUFFIX
|
|-
|Tax1
|FLDCRDTAXCODE1
|
|-
|Tax2
|FLDCRDTAXCODE2
|
|-
|Notes
|FLDCRDNOTES
|
|-
|Title
|FLDCRDTITLE
|
|-
|Last Updated by
|FLDCRDUPDATEUSERID
|When performing updates on existing Account - pass the Foreign Software Name which performs the update.
|-
|Web Address 1
|FLDCRDURL1
|
|-
|Web Address 2
|FLDCRDURL2
|
|-
|Status
|FLDCRDUSER1
|
|-
|Field1
|FLDCRDUSER2
|
|-
|Field2
|FLDCRDUSER3
|
|-
|Field3
|FLDCRDUSER4
|
|-
|Field4
|FLDCRDUSER5
|
|}

===Ticket Fields===

The table below lists the most important Ticket parameters and behavior:

{| class="wikitable"
|-
! '''Field Name'''
! '''Database Field Name'''
! '''Comment'''
|-
| Account REC ID
| FLDTKTCARDID
|The Account record ID (20 chars). The Account Rec ID can be taken from:
#Account Notes tab, at the bottom by rightclicking the REC ID field and selecting Copy
#ODBC to pull information from the database
#The automated email response when adding a cnew Account with the API
|-
| Contact REC ID
| FLDTKTCONTACTID
|The Contact for this Account. If not provided, the main Contact for the Account is taken.
|-
| Contract REC ID
| FLDTKTBCRECID
|The Contract ID. If not supplied, will be taken from the Account's default contract.
|-
| Emp. REC ID
| FLDTKTWORKERID
|The worker ID to be linked to the Ticket. Must be an active employee. This is an optional parameter. If not passed, the system default will be used.
|-
| Priority
| FLDTKTPRIORITY
| The ticket priority. If not passed in the transaction, the default value for new Tickets will be used.
Immediate = 10 High = 20 Normal = 30 Low = 40 Not Applicable= 50
|-
| Ticket Number
| FLDTKTTICKETNO
| The Ticket number. If passed, must be an existing Ticket, and this will update the Ticket with the details in the transaction.
|-
|Description
|FLDTKTPROBLEM
|This is the Ticket Description. This is a mandatory field, which must contain text.
|-
|Ticket Type
|FLDTKTKIND
|Ticket Type (optional). The Ticket Type string should be passed. If not provided, default is used.
|-
|Source
|FLDTKTSOURCE
|
|-
|Estimated Duration Time
|FLDTKTSCHEDLENESTIM
|Estimated duration time for the Ticket in minutes.
|-
|Show Ticket in Dispatcher
|FLDTKTFORDISPATCH
|Possible values: Yes/No
|-
|Status
|FLDTKTSTATUS
|The Ticket Status (optional). 
Possible values: 
New = 100 
Pending = 200 
Scheduled = 300 
In-House Service = 400 
On-Site Service = 500 
Laboratory Service = 600 
Hold = 700 
Other = 800 
Canceled = 900 
Completed = 1000
|-
|Created by User
|FLDTKTCREATEUSER
|Should contain the external software name which created the Ticket
|-
|Due Date
|FLDTKTDUEDATETIME
|Due date for the Ticket. Should be passed in date format. e.g. MM/DD/YYYY
|-
|Resolution
|FLDTKTSOLUTION
|Ticket resolution text
|}

===Charge Fields===
The table below lists the most important Charge parameters and behavior.

Contract-price Charges have some special characteristics (see comments marked by * in
the table below):

{| class="wikitable"
|-
! '''Field Name'''
! '''Database Field Name'''
! '''Comment'''
|-
| Record ID
| FLDSLPRECID
|The Charge record ID. If provided, the existing Charge will be updated. Otherwise, this will be
added as a new Charge.
|-
| Charge Source
| FLDSLPSOURCERECID
|The Charge source is the entity for which the charge is created. 
Possible values:
*Linked Contract RecID (for Contract-price Charges). Cannot be the "System Global Contract".
**Passing the Contract RecID indicates that this is a Contract-price charge.
*Entity RecID from which the charge is created (for example when creating a charge from an Appointment or Task).
|-
| Account REC ID
| FLDSLPCARDID
|The Account record ID (20 chars). The Account REC ID can be taken from:
#Account Notes tab, at the bottom by rightclicking the REC ID field and selecting Copy
#ODBC to pull information from the database
#The automated email response when adding a new Account with the API
|-
| Employee REC ID
| FLDSLPWORKERID
| The worker record ID to be linked to the Charge. Must be an active employee. This is an optional parameter. If not passed, the system default will be used.
|-
| Charged Item
| FLDSLPITEMID
| The Item Record ID to be linked to the Charge. This is a mandatory field.
*For Contract-price Charge can be only Fixed-Price, Unit-based Item.
|-
| Contract REC ID
| FLDSLPBCRECID
| The contract record ID (must be a Contract of the Account)
|-
|Ticket REC ID
|FLDSLPTICKETID
|The Ticket ID to be linked to the Charge.
*Not relevant for Contract-price Charge
|-
|Date
|FLDSLPSLIPDATE
|The date for the Charge. This is an optional parameter. If not provided, the current date will
be used. Should be passed in date format. e.g. MM/DD/YYYY
|-
|Description
|FLDSLPDESC
|The Charge Description. If not provided, will be taken from the Item's description.
|-
|Units/Hours
|FLDSLPQUANTITY
|This is the quantity of hours/units
|-
|Adjust Amount
|FLDSLPADJUSTAMOUNT
|Discount/Markup amount. Positive number means Markup, negative number means Discount.
|-
|Adjust Percent
|FLDSLPADJUSTPERCENT
|Discount/Markup in percentage, must be between (-100) - 100. Positive number means Markup, negative number means Discount.
|-
|From Time
|FLDSLPSTARTTIME
|From time for labor Charges e.g. 12:06
*Not relevant for Contract-price Charge
|-
|To Time
|FLDSLPENDTIME
|From time for labor Charges e.g. 14:50
* Not relevant for Contract-price Charge
|-
|Price/Rate
|FLDSLPPRICE
|If not provided, the price is taken from the Item.
|-
| Billable
| FLDSLPBILLKIND
| B - Billable 
N - Not Billable 
If not provided, will be set according to the Contract type.
|-
| Billed
| FLDSLPSTAGE
| D - Draft
B - Billed
|-
| Field1
| FLDSLPUSER1
| User defined field
|-
| Create User
| FLDSLPCREATEUSER
| External software name which created the Charge
|}

===Item Fields===

The table below lists the most important Item parameters and behavior:

{| class="wikitable"
|-
! '''Field Name'''
! '''Database Field Name'''
! '''Comment'''
|-
| Record ID
| FLDSLPRECID
|The Item record ID. If provided, the existing item will be updated. Otherwise, this will be added as a new item.
|-
| Item Group
| FLDITMITEMTYPEGROUP
|The Item Group to be linked to the Charge. This is a mandatory field: 
F - Labor (Fee) 
X - Expense 
P - Part
|-
| Item Code
| FLDITMITEMNO
|The item code is a mandatory field
|-
| Item Name
| FLDITMNAME
| The item name is a mandatory field
|-
| Price Source
| FLDITMPRICESOURCE
| F - Fixed Price 
W - by Employee Rate
|-
| Price per Hour/Unit
| FLDITMUNITISHOUR
| This field indicated whether the price is unitbased or hours-based. 
Y - by Hours 
N - by Units 
This is an optional field, depending on the Item Group. For example, if the item group is Labor, and Price Source is By Employee, the value will always be by hours
|-
|Price
|FLDITMUNITPRICE
|Must be a valid numeric value
|-
|Cost
|FLDITMSTANDARDCOST
|The date for the Charge. This is an optional parameter. If not provided, the current date will
be used. Should be passed in date format. e.g. MM/DD/YYYY
|-
|Taxes
|FLDITMTAXCODE1 
FLDITMTAXCODE2 
FLDITMTAXCODE3
|You can pass up to 3 different tax codes.
|-
|Description by Name
|FLDITMDESCBYNAME
|Y - take the description from the name field 
N - take the description from the Description field
|-
|Description
|FLDITMDESC
|If not provided, the description is taken from the name.
|-
|Suspend
|FLDITMSUSPENDED
|Indicated whether this item is currently suspended: 
Y - yes 
N - no
|-
|Notes
|FLDITMNOTES
|
|-
|Field1
|FLDSLPUSER1
|User defined field
|-
|Create User
|FLDSLPCREATEUSER
|External software name which created the Charge
|-
| Created by User
| FLDTKTCREATEUSER
| Should contain the external software name which created the Ticket
|}

===History Note Fields===
The table below lists the most important History Note parameters and behavior:

{| class="wikitable"
|-
! '''Field Name'''
! '''Database Field Name'''
! '''Comment'''
|-
| Record ID
| FLDHISRECID
|The History Note record ID. If provided, the existing History Note will be updated. otherwise, this will be added as a new History Note.
|-
| Date
| FLDHISNOTEDATETIME
|Any date format, such as DD/MM/YYYY
|-
| Description
| FLDHISDESCRIPTION
| The Description text
|-
| Opportunity/Ticket/Contract
| FLDHISLINKRECID
| Link to Opportunity or Ticket or Contract
|-
| Field
| FLDHISUSER1
| User defined field
|-
| About
| FLDHISKIND
| Optional field
|-
|Employee
|FLDHISWORKERID
|The worker ID to be linked to the Ticket. Must be an active employee. This is an optional parameter. If not passed, the system default will be used.
|-
|Account
|FLDHISCARDID
|The Account record ID (20 chars). The Account Rec ID can be taken from:
#Account Notes tab, at the bottom, right-click the REC ID field and use Copy. e.g. CRDVQYSOD1B4U4HZIQJJ
#Using ODBC to pull information from the database
#From the Email Response when adding new Account with the API
|-
|Contact
|FLDHISCONTACTID
|The Contact for this Account. If not provided, the main Contact for the Account is taken.
|-
|Document
|FLDHISDOCID
|Linked Document ID, can be taken from the Document Properties window (right-click RecID and use Copy), or using the ODBC to pull information from the database.
|-
|Created by User
|FLDHISCREATEUSER
|Name of the external software which created this History Note
|}

===Asset Fields===
The table below lists the most important Asset parameters and behavior:

{| class="wikitable"
|-
! '''Field Name'''
! '''Database Field Name'''
! '''Comment'''
|-
| Asset Code
| FLDASTASSETCODE
|If an existing Asset Code is provided, then existing Asset is updated. Otherwise a new Asset is added.
|-
| Asset Type
| FLDASTASSETTYPE
|The Type field is mandatory: 
Hardware = H 
Software = S 
Other = T
|-
| Asset Name
| FLDASTNAME
|
|-
| Status
| FLDASTSTATUS
| Mandatory field. 
Active = A 
Not Active = N 
If not provided, default Active is used.
|-
| Record ID
| FLDASTRECID
| If provided, must exist in the database. Ignored if empty
|-
| Serial No.
| FLDASTSERIALNO
|
|-
|Account
|FLDASTACCRECID
|The Account which is linked to the Asset
|-
|Contact
|FLDASTCONTACTRECID
|The Contact for this Account. If not provided, the main Contact for the Account is taken.
|-
|Created by user
|FLDASTCREATEUSER
|Name of external software which created this Asset
|-
|Purchase Date
|FLDASTCUSTPURDATE
|Any date format, such as DD/MM/YYYY
|-
|Purchased From Us
|FLDASTCUSTPURFROMUS
|Possible values: Y/N. 
If not provided, default value Y is used.
|-
| Purchase Invoice #
| FLDASTCUSTPUROURINV
|
|-
| Customer PO
| FLDASTCUSTPURPO
|
|-
| Purchase Price
| FLDASTCUSTPURPRICE
|
|-
| Delivered Date
| FLDASTDELIVEDATE
|
|-
| Description
| FLDASTDESC
|
|-
| Installed By
| FLDASTINSTALBY
|
|-
| Installed Date
| FLDASTINSTALDATE
|
|-
| License Codes
| FLDASTLICENSECODE
|
|-
| License Keys
| FLDASTLICENSEKEY
|
|-
| License Notes
| FLDASTLICENSENOTES
|
|-
| Location
| FLDASTLOCATION
|
|-
| Manufacturer
| FLDASTMANUFACTURER
|
|-
| Mnf Serial No.
| FLDASTMNFSERIALNO
|
|-
| Model
| FLDASTMODEL
|
|-
| Notes
| FLDASTNOTES
|
|-
| Quantity
| FLDASTQUANTITY
| If not provided, default value of 1 is used.
|-
| Last Update By
| FLDASTUPDATEUSER
| Name of externals software which performed the update
|-
| Field1
| FLDASTUSER1
| User defined field
|-
| Field2
| FLDASTUSER2
| User defined field
|-
| Field3
| FLDASTUSER3
| User defined field
|-
| Field4
| FLDASTUSER4
| User defined field
|-
| Field5
| FLDASTUSER5
| User defined field
|-
| Date1
| FLDASTUSERDATE1
| User defined field
|-
| Number1
| FLDASTUSERNUMBER1
| User defined field
|-
| Vendor Purchased Date
| FLDASTVENDORDATEPURC
|
|-
| Vendor Invoice #
| FLDASTVENDORINVNO
|
|-
| Vendor PO
| FLDASTVENDOROURPO
|
|-
| Vendor Price
| FLDASTVENDORPRICE
|
|-
| Vendor
| FLDASTVENDORRECID
|
|-
| Vendor Serial No.
| FLDASTVENDORSERNO
|
|-
| Vendor Warranty Exp. Date
| FLDASTVENDORWARREXP
| Any date format, such as DD/MM/YYYY
|-
| Version
| FLDASTVERSION
|
|-
| Warranty/License Exp.
| FLDASTWARREXPDATE
| Any date format, such as DD/MM/YYYY
|-
| Date
|
|
|}

===Calendar Fields===
The table below lists the most important Calendar parameters and behavior:

{| class="wikitable"
|-
! '''Field Name'''
! '''Database Field Name'''
! '''Comment'''
|-
| Record ID
| FLDEVTRECID
|The Appointment/Task record ID. If provided, the existing entity will be updated. Otherwise, this
will be added as a new Appointment/Task.
|-
| Event Type
| FLDEVTWRITETOID
|The Event type is a mandatory field. 
Appointment = 1 
Task = 2
|-
| Employee
| FLDEVTWORKERID
| The Task/Appointment owner (for private events)
|-
| Private: User
| FLDEVTPRIVATEID
| Possible values: Y/N 
If an Employee was set, this field must be Y
|-
| Account
| FLDEVTCARDID
| The Account record ID (20 chars). The Account REC ID can be taken from:
#Account Notes tab, at the bottom by rightclicking
the REC ID field and selecting Copy
#ODBC to pull information from the database
#The automated email response when adding a
new Account with the API
|-
| Contact
| FLDEVTCONTACTID
| The Contact for this Account. If not provided, the main Contact for the Account is taken.
|-
|Document
|FLDEVTDOCID
|Linked Document ID, can be taken from the Document Properties window (right-click RecID and use Copy), or using the ODBC to pull information from the database.
|-
|Done Indication
|FLDEVTDONE
|Possible values: Y/N
|-
|Date
|FLDEVTEVENTDATE
|The Appointment/Task date is a mandatory field of Any date format, such as DD/MM/YYYY. If not
provided, the current date will be used.
|-
|Description
|FLDEVTFREETEXT
|
|-
|Time: Start
|FLDEVTFROMTIME
|Mandatory field
|-
| Time: End
| FLDEVTTOTIME
| Relevant only for Appointments. If this parameter is not provided, 30 min. interval from Start Time is used.
|-
| Opportunity/Ticket
| FLDEVTLINKRECID
| Linked Ticket/Opportunity/Contract/Asset
|-
| Field1
| FLDEVTFAMILY
| User Defined field
|-
| Field2
| FLDEVTACTION
| User Defined field
|-
| Field3
| FLDEVTPLACE
| User Defined field
|-
| Field4
| FLDEVTPLACE1
| User Defined field
|-
| Field5
| FLDEVTPLACE2
| User Defined field
|-
| Created by User
| FLDEVTCREATEUSERID
| Name of external software which created the event
|-
| Last Update: By User
| FLDEVTUPDATEUSER
| Name of external software which updated the
event
|}

===Opportunity Fields===
The table below lists the most important Opportunity parameters and behavior:

{| class="wikitable"
|-
! '''Field Name'''
! '''Database Field Name'''
! '''Comment'''
|-
| Record ID
| FLDOPPRECID
| The Opportunity record ID. If provided, the existing Opportunity will be updated. Otherwise, this will be added as a new Opportunity.
|-
| Opportunity Name
| FLDOPPNAME
| Mandatory field.
|-
| Opportunity ID
| FLDOPPUSERID
| Optional (Oppty ID)
|-
| Account
| FLDOPPCARDID
| The Account record ID (20 chars). The Account REC ID can be taken from:
#Account Notes tab, at the bottom by right-clicking the REC ID field and selecting Copy
#ODBC to pull information from the database
#The automated email response when adding a new Account with the API
|-
| Contact
| FLDEVTCONTACTID
| The Contact for this Account. If not provided, the main Contact for the Account is taken.
|-
| Source
| FLDOPPSOURCE
|
|-
|Document
|FLDEVTDOCID
|Linked Document ID, can be taken from the Document Properties window (right-click RecID and use Copy), or using the ODBC to pull information from the database.
|-
|Done Indication
|FLDEVTDONE
|Possible values: Y/N
|-
|Close Date
|FLDOPPCLOSEDATE
|
|-
|Manager
|FLDOPPWORKERID
|The Manager's REC ID
|-
|Open Date
|FLDOPPOPENDATE
|
|-
| Close By Date
| FLDOPPESTDATE
| Opportunity must be closed by this date
|-
| Amount
| FLDOPPAMOUNT
|
|-
| Probability %
| FLDOPPPROBABILITY
|
|-
| Stage
| FLDOPPSTAGE
|
|-
| Status
| FLDOPPSTATUS
|
|-
| Closing Amount
| FLDOPPCLOSEAMOUNT
|
|-
| Description
| FLDOPPDESCRIPTION
|
|-
| Opportunity Type
| FLDOPPKIND
|
|-
| Opportunity Reason
| FLDOPPREASON
|
|-
| Note
| FLDOPPNOTES
|
|-
| Territory
| FLDOPPREGION
|
|-
| Field1
| FLDEVTFAMILY
| User Defined field
|-
| Field2
| FLDEVTACTION
| User Defined field
|-
| Field3
| FLDEVTPLACE
| User Defined field
|-
| Created by User
| FLDEVTCREATEUSERID
| Name of external software which created the event
|-
| Last Update: By User
| FLDEVTUPDATEUSER
| Name of external software which updated the event
|}

===Document Fields===
The table below lists the Document parameters and behavior:

{| class="wikitable"
|-
! '''Field Name'''
! '''Database Field Name'''
! '''Comment'''
|-
| Record ID
| FLDDOCRECID
| The Document record ID. If provided, the existing Document will be updated. Otherwise, this will be added as a new Document.
|-
| Document Date
| FLDDOCDOCDATE
| The date for the Document. This is an optional parameter. If not provided, or if the value is illegal, the current date will be used. Should be passed in date format. e.g. MM/DD/YYYY
|-
| Subject
| FLDOPPUSERID
|
|-
| Linked Record
| FLDDOCLINKRECID
| The RECID of a linked object. Each Document can be linked to one of the following objects:
*Ticket
*Contract
*Opportunity
*Knowledge Base Article
*Asset
The Record ID (20 chars) can be taken from:
#Object's Notes tab, at the bottom by right-clicking the REC ID field and selecting Copy
#ODBC to pull information from the database
#The automated email response when adding a new object with the API.
|-
| Account Rec ID
| FLDDOCCARDID
| The Account record ID (20 chars). The Account REC ID can be taken from:
#Account Notes tab, at the bottom by right-clicking the REC ID field and selecting Copy
#ODBC to pull information from the database
#The automated email response when adding a new Account with the API
|-
| Contact REC ID
| FLDDOCCONTACTID
| The Contact for this Account. If not provided, the main Contact for the Account is taken.
|-
|Field1
|FLDDOCTRANSPORT
|User Defined field
|-
|Field2
|FLDDOCFOLDER
|User Defined field
|-
|Field3
|FLDDOCUMENTPLACE
|User Defined field
|-
|File Path + File name
|FLDDOCDOCUMENTNAME
|The Document path
|-
|Category
|FLDDOCTREEID
|The category record ID should be taken from the database table called TreeTbl which contains the Category tree
|-
| Employee REC ID
| FLDDOCWORKERID
| The worker record ID to be linked to the Document. Must be an active employee. This is an optional parameter. If not passed, the system default will be used.
|-
| Created by User
| FLDDOCCREATEUSER
| Name of external software which created the document
|-
| Last Update: By User
| FLDDOCUPDATEUSER
| Name of external software which updated the document
|}

===Knowledge Base Article Fields===
The table below lists the Knowledge Base Article parameters and behavior:

{| class="wikitable"
|-
! '''Field Name'''
! '''Database Field Name'''
! '''Comment'''
|-
| Record ID
| FLDKBARECID
| The Article record ID. If provided, the existing Article will be updated. Otherwise, this will be added as a new Article.
|-
| Document Date
| FLDKBACREATEDATE
| The date for the Document. This is an optional parameter. If not provided, or if the value is illegal, the current date will be used. Should be passed in date format. e.g. MM/DD/YYYY
|-
| Title
| FLDKBATITLE
|
|-
| Problem
| FLDKBAPROBLEM
|
|-
| Solution
| FLDKBASOLUTION
|
|-
| Status
| FLDKBASTATUS
| Possible values:
*DRAFT = 'D'
*PUBLISHED = 'P'
*OBSOLETE = 'O'
|-
|Category
|FLDKBACATEGORY
|
|-
|Public
|FLDKBAISPUBLIC
|Is the Document public. 
Possible values: 
*'Y' = Yes
*'N' = No
|-
|Created by User
|FLDDOCCREATEUSER
|Name of external software which created the document
|-
|Last Update: By User
|FLDDOCUPDATEUSER
|Name of external software which updated the document
|}

===Error Codes Description===
These error codes are returned when calling the CmtGetDescriptionByStatus function: 
'''1000''' CmtDbEng.dll not found. 
'''1001''' Invalid value for the Data Kind value. 
'''1002''' Invalid DATA buffer received. Make sure you have allocated the buffer correctly and
that you have passed the correct buffer length. 
'''1003''' Invalid MAP buffer received. Make sure you have allocated the buffer correctly and
that you have passed the correct buffer length. 
'''1004''' Invalid REC ID buffer received. Make sure you have allocated the buffer correctly
and that you have passed the correct buffer length. 
'''1005''' Invalid LOG buffer received. Make sure you've allocated the buffer correctly and
that you've passed the correct buffer length. 
'''1006''' Invalid REC ID buffer received. It should be at least 20 characters. 
'''1007''' Invalid external software name received. Specify a unique name that identifies your
software. 
'''1008''' Cannot process the transaction. Make sure to call the INIT procedure at least once
prior to sending transactions for processing. 
'''1009''' Path specified for Commit DB folder not found. 
'''1010''' Path specified for Commit DB folder found, but its contents do not reflect a valid DB
folder. 
'''1011''' The RED ID received for the employee/user was not found in Commit, is invalid or is
related to an inactive employee record. 
'''1012''' Error registering software. 
'''1013''' Software name is missing. Make sure you specify a name that identifies your
software. 
'''1014''' Software name is less than 3 characters long. Make sure you enter a software name
that has 3 to 15 characters. 
'''1015''' Software name is too long. Make sure your software name has 3 to 15 characters. 
'''1100''' Database access error. 

General error codes, returned when calling the functions CmtGetDescriptionByCode: 
'''50000''' The data is not correct for its type. 
'''50001''' The field value has been truncated due to the field length in the database. 
'''50002''' The insert operation Failed because the REC ID already existed in the database. 
'''50003''' Failed to update Record since it is being updated by another user. 
'''50103''' Illegal REC ID. 
'''50104''' REC ID Creation failed. 
'''50105''' Illegal Sub-Contact REC ID. 
'''50106''' Illegal Contract REC ID. 
'''50107''' Illegal Employee REC ID. 
'''50108''' Illegal Ticket REC ID. 
'''50109''' Illegal Account REC ID. 
'''50110''' Illegal data for that Contract. 
'''50111''' This Employee is not active. 
'''50112''' Illegal Document REC ID. 
'''50113''' Illegal linked object REC ID. 
'''50114''' Employee not found. 
'''50115''' Some mandatory fields have no values. 
'''51000''' Illegal kind of Account entity. 
'''51001''' Account Manager not found. 
'''51002''' The REC ID of the Account Manager is illegal. 
'''51003''' Illegal tax code. 
'''51004''' This code does not exist in Commit. 
'''52000''' Illegal kind of event. 
'''52001''' Illegal start time. 
'''52002''' Illegal end time. 
'''52003''' Illegal event date. 
'''52004''' The field Reminder1 has Illegal Value. 
'''52005''' The amount in the field has an illegal value. 
'''52006''' The Field Remider1:Units has Illegal Value. 
'''52007''' The Field Remider2:Active has Illegal Value. 
'''52008''' The Field Remider2:Amount has Illegal Value. 
'''52009''' The Field Remider2:Units has Illegal Value. 
'''52010''' Illegal employee REC ID. 
'''52011''' Error occurred while updating the Task/Appointment employee field. 
'''54000''' Illegal Ticket open date. 
'''54001''' Illegal Ticket close date. 
'''54002''' Illegal Ticket code area. 
'''54004''' Illegal Ticket priority. 
'''54005''' Illegal Ticket status. 
'''54006''' The Ticket Account was not found in the database. 
'''54007''' The Ticket Account Manager was not ound in the database. 
'''54008''' This code does not exist in Commit. 
'''54009''' This code does not exist in Commit. 
'''54010''' This code does not exist in Commit. 
'''54011''' This code does not exist in Commit. 
'''54012''' This code does not exist in Commit. 
'''55000''' Illegal charge date. 
'''55001''' Illegal charge REC ID. 
'''55002''' Illegal start date. 
'''55003''' Illegal start time. 
'''55004''' Illegal amount entered for hours. 
'''55005''' Illegal quantity. 
'''55006''' Illegal price. 
'''55007''' Illegal total. 
'''55008''' Illegal value in the Adjust Amount field. 
'''55009''' Illegal value in the Adjust Percent. 
'''55010''' The Discount/Markup field has an illegal value. 
'''55011''' Illegal value in the Adjust Kind field. 
'''55012''' Illegal bill total. 
'''55013''' You can not create a charge for a suspended item. 
'''55014''' Item was not found in Commit. 
'''55015''' This code does not exist in Commit. 
'''55016''' This code does not exists in Commit. 
'''55017''' This Code does not exist in Commit. 
'''55018''' This Code does not exist in Commit. 
'''55019''' This Code does not exist in Commit. 
'''55020''' This Code does not exist in Commit. 
'''55021''' This Code does not exist in Commit. 
'''56000''' Illegal item code. 
'''56001''' The field that indicates the item group type has an illegal value. 
'''56002''' The field that indicates if the Item is suspended has an illegal value. 
'''56003''' Illegal value of The field that indicate if the item is suspended. 
'''56004''' Mismatch found between the fields price and price source. 
'''56005''' Illegal cost. 
'''56006''' Mismatch found between the fields cost and item group type. 
'''56007''' The field that indicates if the charge is by unit or by hours has an illegal value. 
'''56008''' Illegal value in the Description. 
'''56009''' The field that indicates the item type has an illegal value. 
'''57000''' This Code does not exist in Commit. 
'''58000''' Illegal date time. 
'''58001''' The Description field was not found. 
'''58002''' The field kind was not found. 
'''58003''' The Account member was not found. 
'''59000''' This code does not exists in Commit. 
'''59001''' This Code does not exist in Commit. 
'''59002''' This Code does not exist in Commit. 
'''59003''' This Code does not exist in Commit. 
'''59004''' This Code does not exist in Commit. 
'''59005''' This Code does not exist in Commit. 
'''60000''' Invalid web user record ID number. 
'''60001''' This customer web user is not active. 
'''60002''' This user is not a customer. 

==See Also==
*[[Commit API Developers Guide]]
*[[API Code Samples]]
[[Category:User Manuals]]
[[Category:Integration]]

__NOTOC__

API Reference Manual

2010-02-23T14:18:08Z

Reno: /* Account Fields */

{{usermanualsapidevelopersguide}}
==Intorduction==

Following is a detailed listing of fields per entity which can be added/updated using the API. The API parameters are the same when using the Programming API or the XML API.

The API allows you to add/update the following entities:
*[[#Account Fields|Accounts]]
*[[#Ticket Fields|Tickets]]
*[[#Charge Fields|Charges (and Contract-price Charges)]]
*[[#Item Fields|Items]]
*[[#History Note Fields|History Notes]]
*[[#Asset Fields|Assets]]
*[[#Calendar Fields|Calender]]
*[[#Opportunity Fields|Opportunities]]
*[[#Document Fields|Documents]]
*[[#Knowledge Base Article Fields|Knowledge Base Articles]]

All API functions may return error codes. You can find the possible error codes in:
*[[#Error Codes Description|Error Codes]]

In the following section you will find a detailed listing of the database fields. Each table includes the fields '''Display name''' (as shows in the application), the '''Database Field Name''' (internal database field identifier) and comments.

Note that when using XML formatted messages, the database field name refers to the name to be provided within the XML token. For example, when the field name is FLDSLPQUANTITY, the XML token should look like this:
<FLDSLPQUANTITY>10</FLDSLPQUANTITY>

The following table shows the data kind code when using XML or when using the API functions:

{| class="wikitable"
|-
! '''Application entity'''
! '''Table name'''
! '''Programming Code'''
! '''XML Data Kind Name'''
|-
| Accounts
| Cards
| 10
| ACCOUNT
|-
| Opportunities
| Opps
| 20
| OPPORTUNITY
|-
| Documents
| Docs
| 30
| DOCUMENT
|-
| Charges
| Slips
| 40
| CHARGE
|-
| Appointments/Tasks
| Events
| 50
| APPOINTMENT-OR-TASK
|-
| History Notes
| Notebook
| 60
| HISTORY-NOTE
|-
| Tickets
| Tickets
| 70
| TICKET
|-
| Items
| Items
| 80
| ITEM
|-
| Assets
| Assets
| 90
| ASSET
|-
| Knowledge Base
| KBArticles
| 100
| KBARTICLE
|}
You can find examples of adding and updating records in the database by using the database field in the [[API Code Samples]] section.

===Account Fields===
The following table lists the most important parameters for adding/updating Account
records.
Note slight differences when adding a main account vs. adding a secondary contact.

{| class="wikitable"
|-
! '''Field Name'''
! '''Database Field Name'''
! '''Comment'''
|-
| Account REC ID
| FLDCRDRECID
|The Account record ID (20 chars). The Account Rec ID can be taken from:
#Account Notes tab, at the bottom, rightclick the RecID field and use Copy. e.g. CRDVQYSOD1B4U4HZIQJJ
#Using ODBC to pull information from the database.
#From the Email Response when adding new Account with the API.
|-
| Account Manager
| FLDCRDASSIGNCARDID
| This field has two roles:
#When adding a main Account: The account manager should contain the ID of the Employee who is the account manager.
#When adding a secondary contact: 
This field should contain the ID of the main Account to which the secondary contacted is
added.
|-
|Company name
|FLDCRDCOMPANY
|
|-
|Contact: First & Last Name
|FLDCRDCONTACT
|
|-
| Assistant
| FLDCRDASSISTANT
|
|-
|Contract
|FLDCRDBCRECID
|The default Contract for this Account (not required)
|-
|Account Number
|FLDCRDCARDID2
|
|-
|ID
|FLDCRDCARDID3
|
|-
|Popup Message
|FLDCRDCARDMESSAGE
|
|-
| Address: Line1
| FLDCRDADDRESS1
|
|-
| Address: Line2
| FLDCRDADDRESS2
|
|-
| Address: Line3
| FLDCRDADDRESS3
|
|-
|Address: City
|FLDCRDCITY
|
|-
|Address: State
|FLDCRDCOUNTRY
|
|-
|Address: Country
|FLDCRDSTATE
|
|-
|Address: Zip
|FLDCRDZIP
|
|-
|Creation Date
|FLDCRDCREATEDATE
|Any date format, such as DD/MM/YYYY
|-
|Created by User
|FLDCRDCREATEUSERID
|Foreign Software Name which created the account
|-
|Dear
|FLDCRDDEAR
|
|-
|Department
|FLDCRDDEPARTMENT
|
|-
|Documents Store Directory
|FLDCRDDOCSFOLDER
|
|-
|E-Mail Address 1
|FLDCRDEMAIL1
|
|-
|E-Mail Address 2
|FLDCRDEMAIL2
|
|-
|Account Type
|FLDCRDENTITYKIND
|When adding a Main Account = 1 When adding a secondary contact = 5
|-
|Fax Number
|FLDCRDFAX1
|
|-
|Fax Number Extension
|FLDCRDFAXDESC1
|
|-
|File as
|FLDCRDFULLNAME
|
|-
|Type
|FLDCRDKIND
|
|-
|Last Name
|FLDCRDLASTNAME
|
|-
|Notes
|FLDCRDNOTES
|
|-
|Field
|FLDCRDPERSONID
|
|-
|Phone 1 Ext.
|FLDCRDPHNDESC1
|
|-
|Phone 2 Ext.
|FLDCRDPHNDESC2
|
|-
|Phone 3 Ext.
|FLDCRDPHNDESC3
|
|-
|Phone 4 Ext.
|FLDCRDPHNDESC4
|
|-
|Phone 1
|FLDCRDPHONE1
|
|-
|Phone 2
|FLDCRDPHONE2
|
|-
|Phone 3
|FLDCRDPHONE3
|
|-
|Phone 4
|FLDCRDPHONE4
|
|-
|Region
|Region FLDCRDREGIONCODE
|
|-
|Popup Message: Display Indication
|FLDCRDSHOWMESSAGE
|
|-
|Sub-Contact Code
|FLDCRDSUBCODE
|
|-
|Salutation
|FLDCRDSUFFIX
|
|-
|Tax1
|FLDCRDTAXCODE1
|
|-
|Tax2
|FLDCRDTAXCODE2
|
|-
|Notes
|FLDCRDNOTES
|
|-
|Title
|FLDCRDTITLE
|
|-
|Last Updated by
|FLDCRDUPDATEUSERID
|When performing updates on existing Account - pass the Foreign Software Name which performs the update.
|-
|Web Address 1
|FLDCRDURL1
|
|-
|Web Address 2
|FLDCRDURL2
|
|-
|Status
|FLDCRDUSER1
|
|-
|Field1
|FLDCRDUSER2
|
|-
|Field2
|FLDCRDUSER3
|
|-
|Field3
|FLDCRDUSER4
|
|-
|Field4
|FLDCRDUSER5
|
|}

===Ticket Fields===

The table below lists the most important Ticket parameters and behavior:

{| class="wikitable"
|-
! '''Field Name'''
! '''Database Field Name'''
! '''Comment'''
|-
| Account REC ID
| FLDTKTCARDID
|The Account record ID (20 chars). The Account Rec ID can be taken from:
#Account Notes tab, at the bottom by rightclicking the REC ID field and selecting Copy
#ODBC to pull information from the database
#The automated email response when adding a cnew Account with the API
|-
| Contact REC ID
| FLDTKTCONTACTID
|The Contact for this Account. If not provided, the main Contact for the Account is taken.
|-
| Contract REC ID
| FLDTKTBCRECID
|The Contract ID. If not supplied, will be taken from the Account's default contract.
|-
| Emp. REC ID
| FLDTKTWORKERID
|The worker ID to be linked to the Ticket. Must be an active employee. This is an optional parameter. If not passed, the system default will be used.
|-
| Priority
| FLDTKTPRIORITY
| The ticket priority. If not passed in the transaction, the default value for new Tickets will be used.
Immediate = 10 High = 20 Normal = 30 Low = 40 Not Applicable= 50
|-
| Ticket Number
| FLDTKTTICKETNO
| The Ticket number. If passed, must be an existing Ticket, and this will update the Ticket with the details in the transaction.
|-
|Description
|FLDTKTPROBLEM
|This is the Ticket Description. This is a mandatory field, which must contain text.
|-
|Ticket Type
|FLDTKTKIND
|Ticket Type (optional). The Ticket Type string should be passed. If not provided, default is used.
|-
|Source
|FLDTKTSOURCE
|
|-
|Estimated Duration Time
|FLDTKTSCHEDLENESTIM
|Estimated duration time for the Ticket in minutes.
|-
|Show Ticket in Dispatcher
|FLDTKTFORDISPATCH
|Possible values: Yes/No
|-
|Status
|FLDTKTSTATUS
|The Ticket Status (optional). 
Possible values: 
New = 100 
Pending = 200 
Scheduled = 300 
In-House Service = 400 
On-Site Service = 500 
Laboratory Service = 600 
Hold = 700 
Other = 800 
Canceled = 900 
Completed = 1000
|-
|Created by User
|FLDTKTCREATEUSER
|Should contain the external software name which created the Ticket
|-
|Due Date
|FLDTKTDUEDATETIME
|Due date for the Ticket. Should be passed in date format. e.g. MM/DD/YYYY
|-
|Resolution
|FLDTKTSOLUTION
|Ticket resolution text
|}

===Charge Fields===
The table below lists the most important Charge parameters and behavior.

Contract-price Charges have some special characteristics (see comments marked by * in
the table below):

{| class="wikitable"
|-
! '''Field Name'''
! '''Database Field Name'''
! '''Comment'''
|-
| Record ID
| FLDSLPRECID
|The Charge record ID. If provided, the existing Charge will be updated. Otherwise, this will be
added as a new Charge.
|-
| Charge Source
| FLDSLPSOURCERECID
|The Charge source is the entity for which the charge is created. 
Possible values:
*Linked Contract RecID (for Contract-price Charges). Cannot be the "System Global Contract".
**Passing the Contract RecID indicates that this is a Contract-price charge.
*Entity RecID from which the charge is created (for example when creating a charge from an Appointment or Task).
|-
| Account REC ID
| FLDSLPCARDID
|The Account record ID (20 chars). The Account REC ID can be taken from:
#Account Notes tab, at the bottom by rightclicking the REC ID field and selecting Copy
#ODBC to pull information from the database
#The automated email response when adding a new Account with the API
|-
| Employee REC ID
| FLDSLPWORKERID
| The worker record ID to be linked to the Charge. Must be an active employee. This is an optional parameter. If not passed, the system default will be used.
|-
| Charged Item
| FLDSLPITEMID
| The Item Record ID to be linked to the Charge. This is a mandatory field.
*For Contract-price Charge can be only Fixed-Price, Unit-based Item.
|-
| Contract REC ID
| FLDSLPBCRECID
| The contract record ID (must be a Contract of the Account)
|-
|Ticket REC ID
|FLDSLPTICKETID
|The Ticket ID to be linked to the Charge.
*Not relevant for Contract-price Charge
|-
|Date
|FLDSLPSLIPDATE
|The date for the Charge. This is an optional parameter. If not provided, the current date will
be used. Should be passed in date format. e.g. MM/DD/YYYY
|-
|Description
|FLDSLPDESC
|The Charge Description. If not provided, will be taken from the Item's description.
|-
|Units/Hours
|FLDSLPQUANTITY
|This is the quantity of hours/units
|-
|Adjust Amount
|FLDSLPADJUSTAMOUNT
|Discount/Markup amount. Positive number means Markup, negative number means Discount.
|-
|Adjust Percent
|FLDSLPADJUSTPERCENT
|Discount/Markup in percentage, must be between (-100) - 100. Positive number means Markup, negative number means Discount.
|-
|From Time
|FLDSLPSTARTTIME
|From time for labor Charges e.g. 12:06
*Not relevant for Contract-price Charge
|-
|To Time
|FLDSLPENDTIME
|From time for labor Charges e.g. 14:50
* Not relevant for Contract-price Charge
|-
|Price/Rate
|FLDSLPPRICE
|If not provided, the price is taken from the Item.
|-
| Billable
| FLDSLPBILLKIND
| B - Billable 
N - Not Billable 
If not provided, will be set according to the Contract type.
|-
| Billed
| FLDSLPSTAGE
| D - Draft
B - Billed
|-
| Field1
| FLDSLPUSER1
| User defined field
|-
| Create User
| FLDSLPCREATEUSER
| External software name which created the Charge
|}

===Item Fields===

The table below lists the most important Item parameters and behavior:

{| class="wikitable"
|-
! '''Field Name'''
! '''Database Field Name'''
! '''Comment'''
|-
| Record ID
| FLDSLPRECID
|The Item record ID. If provided, the existing item will be updated. Otherwise, this will be added as a new item.
|-
| Item Group
| FLDITMITEMTYPEGROUP
|The Item Group to be linked to the Charge. This is a mandatory field: 
F - Labor (Fee) 
X - Expense 
P - Part
|-
| Item Code
| FLDITMITEMNO
|The item code is a mandatory field
|-
| Item Name
| FLDITMNAME
| The item name is a mandatory field
|-
| Price Source
| FLDITMPRICESOURCE
| F - Fixed Price 
W - by Employee Rate
|-
| Price per Hour/Unit
| FLDITMUNITISHOUR
| This field indicated whether the price is unitbased or hours-based. 
Y - by Hours 
N - by Units 
This is an optional field, depending on the Item Group. For example, if the item group is Labor, and Price Source is By Employee, the value will always be by hours
|-
|Price
|FLDITMUNITPRICE
|Must be a valid numeric value
|-
|Cost
|FLDITMSTANDARDCOST
|The date for the Charge. This is an optional parameter. If not provided, the current date will
be used. Should be passed in date format. e.g. MM/DD/YYYY
|-
|Taxes
|FLDITMTAXCODE1 
FLDITMTAXCODE2 
FLDITMTAXCODE3
|You can pass up to 3 different tax codes.
|-
|Description by Name
|FLDITMDESCBYNAME
|Y - take the description from the name field 
N - take the description from the Description field
|-
|Description
|FLDITMDESC
|If not provided, the description is taken from the name.
|-
|Suspend
|FLDITMSUSPENDED
|Indicated whether this item is currently suspended: 
Y - yes 
N - no
|-
|Notes
|FLDITMNOTES
|
|-
|Field1
|FLDSLPUSER1
|User defined field
|-
|Create User
|FLDSLPCREATEUSER
|External software name which created the Charge
|-
| Created by User
| FLDTKTCREATEUSER
| Should contain the external software name which created the Ticket
|}

===History Note Fields===
The table below lists the most important History Note parameters and behavior:

{| class="wikitable"
|-
! '''Field Name'''
! '''Database Field Name'''
! '''Comment'''
|-
| Record ID
| FLDHISRECID
|The History Note record ID. If provided, the existing History Note will be updated. otherwise, this will be added as a new History Note.
|-
| Date
| FLDHISNOTEDATETIME
|Any date format, such as DD/MM/YYYY
|-
| Description
| FLDHISDESCRIPTION
| The Description text
|-
| Opportunity/Ticket/Contract
| FLDHISLINKRECID
| Link to Opportunity or Ticket or Contract
|-
| Field
| FLDHISUSER1
| User defined field
|-
| About
| FLDHISKIND
| Optional field
|-
|Employee
|FLDHISWORKERID
|The worker ID to be linked to the Ticket. Must be an active employee. This is an optional parameter. If not passed, the system default will be used.
|-
|Account
|FLDHISCARDID
|The Account record ID (20 chars). The Account Rec ID can be taken from:
#Account Notes tab, at the bottom, right-click the REC ID field and use Copy. e.g. CRDVQYSOD1B4U4HZIQJJ
#Using ODBC to pull information from the database
#From the Email Response when adding new Account with the API
|-
|Contact
|FLDHISCONTACTID
|The Contact for this Account. If not provided, the main Contact for the Account is taken.
|-
|Document
|FLDHISDOCID
|Linked Document ID, can be taken from the Document Properties window (right-click RecID and use Copy), or using the ODBC to pull information from the database.
|-
|Created by User
|FLDHISCREATEUSER
|Name of the external software which created this History Note
|}

===Asset Fields===
The table below lists the most important Asset parameters and behavior:

{| class="wikitable"
|-
! '''Field Name'''
! '''Database Field Name'''
! '''Comment'''
|-
| Asset Code
| FLDASTASSETCODE
|If an existing Asset Code is provided, then existing Asset is updated. Otherwise a new Asset is added.
|-
| Asset Type
| FLDASTASSETTYPE
|The Type field is mandatory: 
Hardware = H 
Software = S 
Other = T
|-
| Asset Name
| FLDASTNAME
|
|-
| Status
| FLDASTSTATUS
| Mandatory field. 
Active = A 
Not Active = N 
If not provided, default Active is used.
|-
| Record ID
| FLDASTRECID
| If provided, must exist in the database. Ignored if empty
|-
| Serial No.
| FLDASTSERIALNO
|
|-
|Account
|FLDASTACCRECID
|The Account which is linked to the Asset
|-
|Contact
|FLDASTCONTACTRECID
|The Contact for this Account. If not provided, the main Contact for the Account is taken.
|-
|Created by user
|FLDASTCREATEUSER
|Name of external software which created this Asset
|-
|Purchase Date
|FLDASTCUSTPURDATE
|Any date format, such as DD/MM/YYYY
|-
|Purchased From Us
|FLDASTCUSTPURFROMUS
|Possible values: Y/N. 
If not provided, default value Y is used.
|-
| Purchase Invoice #
| FLDASTCUSTPUROURINV
|
|-
| Customer PO
| FLDASTCUSTPURPO
|
|-
| Purchase Price
| FLDASTCUSTPURPRICE
|
|-
| Delivered Date
| FLDASTDELIVEDATE
|
|-
| Description
| FLDASTDESC
|
|-
| Installed By
| FLDASTINSTALBY
|
|-
| Installed Date
| FLDASTINSTALDATE
|
|-
| License Codes
| FLDASTLICENSECODE
|
|-
| License Keys
| FLDASTLICENSEKEY
|
|-
| License Notes
| FLDASTLICENSENOTES
|
|-
| Location
| FLDASTLOCATION
|
|-
| Manufacturer
| FLDASTMANUFACTURER
|
|-
| Mnf Serial No.
| FLDASTMNFSERIALNO
|
|-
| Model
| FLDASTMODEL
|
|-
| Notes
| FLDASTNOTES
|
|-
| Quantity
| FLDASTQUANTITY
| If not provided, default value of 1 is used.
|-
| Last Update By
| FLDASTUPDATEUSER
| Name of externals software which performed the update
|-
| Field1
| FLDASTUSER1
| User defined field
|-
| Field2
| FLDASTUSER2
| User defined field
|-
| Field3
| FLDASTUSER3
| User defined field
|-
| Field4
| FLDASTUSER4
| User defined field
|-
| Field5
| FLDASTUSER5
| User defined field
|-
| Date1
| FLDASTUSERDATE1
| User defined field
|-
| Number1
| FLDASTUSERNUMBER1
| User defined field
|-
| Vendor Purchased Date
| FLDASTVENDORDATEPURC
|
|-
| Vendor Invoice #
| FLDASTVENDORINVNO
|
|-
| Vendor PO
| FLDASTVENDOROURPO
|
|-
| Vendor Price
| FLDASTVENDORPRICE
|
|-
| Vendor
| FLDASTVENDORRECID
|
|-
| Vendor Serial No.
| FLDASTVENDORSERNO
|
|-
| Vendor Warranty Exp. Date
| FLDASTVENDORWARREXP
| Any date format, such as DD/MM/YYYY
|-
| Version
| FLDASTVERSION
|
|-
| Warranty/License Exp.
| FLDASTWARREXPDATE
| Any date format, such as DD/MM/YYYY
|-
| Date
|
|
|}

===Calendar Fields===
The table below lists the most important Calendar parameters and behavior:

{| class="wikitable"
|-
! '''Field Name'''
! '''Database Field Name'''
! '''Comment'''
|-
| Record ID
| FLDEVTRECID
|The Appointment/Task record ID. If provided, the existing entity will be updated. Otherwise, this
will be added as a new Appointment/Task.
|-
| Event Type
| FLDEVTWRITETOID
|The Event type is a mandatory field. 
Appointment = 1 
Task = 2
|-
| Employee
| FLDEVTWORKERID
| The Task/Appointment owner (for private events)
|-
| Private: User
| FLDEVTPRIVATEID
| Possible values: Y/N 
If an Employee was set, this field must be Y
|-
| Account
| FLDEVTCARDID
| The Account record ID (20 chars). The Account REC ID can be taken from:
#Account Notes tab, at the bottom by rightclicking
the REC ID field and selecting Copy
#ODBC to pull information from the database
#The automated email response when adding a
new Account with the API
|-
| Contact
| FLDEVTCONTACTID
| The Contact for this Account. If not provided, the main Contact for the Account is taken.
|-
|Document
|FLDEVTDOCID
|Linked Document ID, can be taken from the Document Properties window (right-click RecID and use Copy), or using the ODBC to pull information from the database.
|-
|Done Indication
|FLDEVTDONE
|Possible values: Y/N
|-
|Date
|FLDEVTEVENTDATE
|The Appointment/Task date is a mandatory field of Any date format, such as DD/MM/YYYY. If not
provided, the current date will be used.
|-
|Description
|FLDEVTFREETEXT
|
|-
|Time: Start
|FLDEVTFROMTIME
|Mandatory field
|-
| Time: End
| FLDEVTTOTIME
| Relevant only for Appointments. If this parameter is not provided, 30 min. interval from Start Time is used.
|-
| Opportunity/Ticket
| FLDEVTLINKRECID
| Linked Ticket/Opportunity/Contract/Asset
|-
| Field1
| FLDEVTFAMILY
| User Defined field
|-
| Field2
| FLDEVTACTION
| User Defined field
|-
| Field3
| FLDEVTPLACE
| User Defined field
|-
| Field4
| FLDEVTPLACE1
| User Defined field
|-
| Field5
| FLDEVTPLACE2
| User Defined field
|-
| Created by User
| FLDEVTCREATEUSERID
| Name of external software which created the event
|-
| Last Update: By User
| FLDEVTUPDATEUSER
| Name of external software which updated the
event
|}

===Opportunity Fields===
The table below lists the most important Opportunity parameters and behavior:

{| class="wikitable"
|-
! '''Field Name'''
! '''Database Field Name'''
! '''Comment'''
|-
| Record ID
| FLDOPPRECID
| The Opportunity record ID. If provided, the existing Opportunity will be updated. Otherwise, this will be added as a new Opportunity.
|-
| Opportunity Name
| FLDOPPNAME
| Mandatory field.
|-
| Opportunity ID
| FLDOPPUSERID
| Optional (Oppty ID)
|-
| Account
| FLDOPPCARDID
| The Account record ID (20 chars). The Account REC ID can be taken from:
#Account Notes tab, at the bottom by right-clicking the REC ID field and selecting Copy
#ODBC to pull information from the database
#The automated email response when adding a new Account with the API
|-
| Contact
| FLDEVTCONTACTID
| The Contact for this Account. If not provided, the main Contact for the Account is taken.
|-
| Source
| FLDOPPSOURCE
|
|-
|Document
|FLDEVTDOCID
|Linked Document ID, can be taken from the Document Properties window (right-click RecID and use Copy), or using the ODBC to pull information from the database.
|-
|Done Indication
|FLDEVTDONE
|Possible values: Y/N
|-
|Close Date
|FLDOPPCLOSEDATE
|
|-
|Manager
|FLDOPPWORKERID
|The Manager's REC ID
|-
|Open Date
|FLDOPPOPENDATE
|
|-
| Close By Date
| FLDOPPESTDATE
| Opportunity must be closed by this date
|-
| Amount
| FLDOPPAMOUNT
|
|-
| Probability %
| FLDOPPPROBABILITY
|
|-
| Stage
| FLDOPPSTAGE
|
|-
| Status
| FLDOPPSTATUS
|
|-
| Closing Amount
| FLDOPPCLOSEAMOUNT
|
|-
| Description
| FLDOPPDESCRIPTION
|
|-
| Opportunity Type
| FLDOPPKIND
|
|-
| Opportunity Reason
| FLDOPPREASON
|
|-
| Note
| FLDOPPNOTES
|
|-
| Territory
| FLDOPPREGION
|
|-
| Field1
| FLDEVTFAMILY
| User Defined field
|-
| Field2
| FLDEVTACTION
| User Defined field
|-
| Field3
| FLDEVTPLACE
| User Defined field
|-
| Created by User
| FLDEVTCREATEUSERID
| Name of external software which created the event
|-
| Last Update: By User
| FLDEVTUPDATEUSER
| Name of external software which updated the event
|}

===Document Fields===
The table below lists the Document parameters and behavior:

{| class="wikitable"
|-
! '''Field Name'''
! '''Database Field Name'''
! '''Comment'''
|-
| Record ID
| FLDDOCRECID
| The Document record ID. If provided, the existing Document will be updated. Otherwise, this will be added as a new Document.
|-
| Document Date
| FLDDOCDOCDATE
| The date for the Document. This is an optional parameter. If not provided, or if the value is illegal, the current date will be used. Should be passed in date format. e.g. MM/DD/YYYY
|-
| Subject
| FLDOPPUSERID
|
|-
| Linked Record
| FLDDOCLINKRECID
| The RECID of a linked object. Each Document can be linked to one of the following objects:
*Ticket
*Contract
*Opportunity
*Knowledge Base Article
*Asset
The Record ID (20 chars) can be taken from:
#Object's Notes tab, at the bottom by right-clicking the REC ID field and selecting Copy
#ODBC to pull information from the database
#The automated email response when adding a new object with the API.
|-
| Account Rec ID
| FLDDOCCARDID
| The Account record ID (20 chars). The Account REC ID can be taken from:
#Account Notes tab, at the bottom by right-clicking the REC ID field and selecting Copy
#ODBC to pull information from the database
#The automated email response when adding a new Account with the API
|-
| Contact REC ID
| FLDDOCCONTACTID
| The Contact for this Account. If not provided, the main Contact for the Account is taken.
|-
|Field1
|FLDDOCTRANSPORT
|User Defined field
|-
|Field2
|FLDDOCFOLDER
|User Defined field
|-
|Field3
|FLDDOCUMENTPLACE
|User Defined field
|-
|File Path + File name
|FLDDOCDOCUMENTNAME
|The Document path
|-
|Category
|FLDDOCTREEID
|The category record ID should be taken from the database table called TreeTbl which contains the Category tree
|-
| Employee REC ID
| FLDDOCWORKERID
| The worker record ID to be linked to the Document. Must be an active employee. This is an optional parameter. If not passed, the system default will be used.
|-
| Created by User
| FLDDOCCREATEUSER
| Name of external software which created the document
|-
| Last Update: By User
| FLDDOCUPDATEUSER
| Name of external software which updated the document
|}

===Knowledge Base Article Fields===
The table below lists the Knowledge Base Article parameters and behavior:

{| class="wikitable"
|-
! '''Field Name'''
! '''Database Field Name'''
! '''Comment'''
|-
| Record ID
| FLDKBARECID
| The Article record ID. If provided, the existing Article will be updated. Otherwise, this will be added as a new Article.
|-
| Document Date
| FLDKBACREATEDATE
| The date for the Document. This is an optional parameter. If not provided, or if the value is illegal, the current date will be used. Should be passed in date format. e.g. MM/DD/YYYY
|-
| Title
| FLDKBATITLE
|
|-
| Problem
| FLDKBAPROBLEM
|
|-
| Solution
| FLDKBASOLUTION
|
|-
| Status
| FLDKBASTATUS
| Possible values:
*DRAFT = 'D'
*PUBLISHED = 'P'
*OBSOLETE = 'O'
|-
|Category
|FLDKBACATEGORY
|
|-
|Public
|FLDKBAISPUBLIC
|Is the Document public. 
Possible values: 
*'Y' = Yes
*'N' = No
|-
|Created by User
|FLDDOCCREATEUSER
|Name of external software which created the document
|-
|Last Update: By User
|FLDDOCUPDATEUSER
|Name of external software which updated the document
|}

===Error Codes Description===
These error codes are returned when calling the CmtGetDescriptionByStatus function: 
'''1000''' CmtDbEng.dll not found. 
'''1001''' Invalid value for the Data Kind value. 
'''1002''' Invalid DATA buffer received. Make sure you have allocated the buffer correctly and
that you have passed the correct buffer length. 
'''1003''' Invalid MAP buffer received. Make sure you have allocated the buffer correctly and
that you have passed the correct buffer length. 
'''1004''' Invalid REC ID buffer received. Make sure you have allocated the buffer correctly
and that you have passed the correct buffer length. 
'''1005''' Invalid LOG buffer received. Make sure you've allocated the buffer correctly and
that you've passed the correct buffer length. 
'''1006''' Invalid REC ID buffer received. It should be at least 20 characters. 
'''1007''' Invalid external software name received. Specify a unique name that identifies your
software. 
'''1008''' Cannot process the transaction. Make sure to call the INIT procedure at least once
prior to sending transactions for processing. 
'''1009''' Path specified for Commit DB folder not found. 
'''1010''' Path specified for Commit DB folder found, but its contents do not reflect a valid DB
folder. 
'''1011''' The RED ID received for the employee/user was not found in Commit, is invalid or is
related to an inactive employee record. 
'''1012''' Error registering software. 
'''1013''' Software name is missing. Make sure you specify a name that identifies your
software. 
'''1014''' Software name is less than 3 characters long. Make sure you enter a software name
that has 3 to 15 characters. 
'''1015''' Software name is too long. Make sure your software name has 3 to 15 characters. 
'''1100''' Database access error. 

General error codes, returned when calling the functions CmtGetDescriptionByCode: 
'''50000''' The data is not correct for its type. 
'''50001''' The field value has been truncated due to the field length in the database. 
'''50002''' The insert operation Failed because the REC ID already existed in the database. 
'''50003''' Failed to update Record since it is being updated by another user. 
'''50103''' Illegal REC ID. 
'''50104''' REC ID Creation failed. 
'''50105''' Illegal Sub-Contact REC ID. 
'''50106''' Illegal Contract REC ID. 
'''50107''' Illegal Employee REC ID. 
'''50108''' Illegal Ticket REC ID. 
'''50109''' Illegal Account REC ID. 
'''50110''' Illegal data for that Contract. 
'''50111''' This Employee is not active. 
'''50112''' Illegal Document REC ID. 
'''50113''' Illegal linked object REC ID. 
'''50114''' Employee not found. 
'''50115''' Some mandatory fields have no values. 
'''51000''' Illegal kind of Account entity. 
'''51001''' Account Manager not found. 
'''51002''' The REC ID of the Account Manager is illegal. 
'''51003''' Illegal tax code. 
'''51004''' This code does not exist in Commit. 
'''52000''' Illegal kind of event. 
'''52001''' Illegal start time. 
'''52002''' Illegal end time. 
'''52003''' Illegal event date. 
'''52004''' The field Reminder1 has Illegal Value. 
'''52005''' The amount in the field has an illegal value. 
'''52006''' The Field Remider1:Units has Illegal Value. 
'''52007''' The Field Remider2:Active has Illegal Value. 
'''52008''' The Field Remider2:Amount has Illegal Value. 
'''52009''' The Field Remider2:Units has Illegal Value. 
'''52010''' Illegal employee REC ID. 
'''52011''' Error occurred while updating the Task/Appointment employee field. 
'''54000''' Illegal Ticket open date. 
'''54001''' Illegal Ticket close date. 
'''54002''' Illegal Ticket code area. 
'''54004''' Illegal Ticket priority. 
'''54005''' Illegal Ticket status. 
'''54006''' The Ticket Account was not found in the database. 
'''54007''' The Ticket Account Manager was not ound in the database. 
'''54008''' This code does not exist in Commit. 
'''54009''' This code does not exist in Commit. 
'''54010''' This code does not exist in Commit. 
'''54011''' This code does not exist in Commit. 
'''54012''' This code does not exist in Commit. 
'''55000''' Illegal charge date. 
'''55001''' Illegal charge REC ID. 
'''55002''' Illegal start date. 
'''55003''' Illegal start time. 
'''55004''' Illegal amount entered for hours. 
'''55005''' Illegal quantity. 
'''55006''' Illegal price. 
'''55007''' Illegal total. 
'''55008''' Illegal value in the Adjust Amount field. 
'''55009''' Illegal value in the Adjust Percent. 
'''55010''' The Discount/Markup field has an illegal value. 
'''55011''' Illegal value in the Adjust Kind field. 
'''55012''' Illegal bill total. 
'''55013''' You can not create a charge for a suspended item. 
'''55014''' Item was not found in Commit. 
'''55015''' This code does not exist in Commit. 
'''55016''' This code does not exists in Commit. 
'''55017''' This Code does not exist in Commit. 
'''55018''' This Code does not exist in Commit. 
'''55019''' This Code does not exist in Commit. 
'''55020''' This Code does not exist in Commit. 
'''55021''' This Code does not exist in Commit. 
'''56000''' Illegal item code. 
'''56001''' The field that indicates the item group type has an illegal value. 
'''56002''' The field that indicates if the Item is suspended has an illegal value. 
'''56003''' Illegal value of The field that indicate if the item is suspended. 
'''56004''' Mismatch found between the fields price and price source. 
'''56005''' Illegal cost. 
'''56006''' Mismatch found between the fields cost and item group type. 
'''56007''' The field that indicates if the charge is by unit or by hours has an illegal value. 
'''56008''' Illegal value in the Description. 
'''56009''' The field that indicates the item type has an illegal value. 
'''57000''' This Code does not exist in Commit. 
'''58000''' Illegal date time. 
'''58001''' The Description field was not found. 
'''58002''' The field kind was not found. 
'''58003''' The Account member was not found. 
'''59000''' This code does not exists in Commit. 
'''59001''' This Code does not exist in Commit. 
'''59002''' This Code does not exist in Commit. 
'''59003''' This Code does not exist in Commit. 
'''59004''' This Code does not exist in Commit. 
'''59005''' This Code does not exist in Commit. 
'''60000''' Invalid web user record ID number. 
'''60001''' This customer web user is not active. 
'''60002''' This user is not a customer. 

==See Also==
*[[Commit API Developers Guide]]
*[[API Code Samples]]
[[Category:User Manuals]]
[[Category:Integration]]

__NOTOC__

API Reference Manual

2010-02-23T14:16:49Z

Reno: /* Account Fields */

{{usermanualsapidevelopersguide}}
==Intorduction==

Following is a detailed listing of fields per entity which can be added/updated using the API. The API parameters are the same when using the Programming API or the XML API.

The API allows you to add/update the following entities:
*[[#Account Fields|Accounts]]
*[[#Ticket Fields|Tickets]]
*[[#Charge Fields|Charges (and Contract-price Charges)]]
*[[#Item Fields|Items]]
*[[#History Note Fields|History Notes]]
*[[#Asset Fields|Assets]]
*[[#Calendar Fields|Calender]]
*[[#Opportunity Fields|Opportunities]]
*[[#Document Fields|Documents]]
*[[#Knowledge Base Article Fields|Knowledge Base Articles]]

All API functions may return error codes. You can find the possible error codes in:
*[[#Error Codes Description|Error Codes]]

In the following section you will find a detailed listing of the database fields. Each table includes the fields '''Display name''' (as shows in the application), the '''Database Field Name''' (internal database field identifier) and comments.

Note that when using XML formatted messages, the database field name refers to the name to be provided within the XML token. For example, when the field name is FLDSLPQUANTITY, the XML token should look like this:
<FLDSLPQUANTITY>10</FLDSLPQUANTITY>

The following table shows the data kind code when using XML or when using the API functions:

{| class="wikitable"
|-
! '''Application entity'''
! '''Table name'''
! '''Programming Code'''
! '''XML Data Kind Name'''
|-
| Accounts
| Cards
| 10
| ACCOUNT
|-
| Opportunities
| Opps
| 20
| OPPORTUNITY
|-
| Documents
| Docs
| 30
| DOCUMENT
|-
| Charges
| Slips
| 40
| CHARGE
|-
| Appointments/Tasks
| Events
| 50
| APPOINTMENT-OR-TASK
|-
| History Notes
| Notebook
| 60
| HISTORY-NOTE
|-
| Tickets
| Tickets
| 70
| TICKET
|-
| Items
| Items
| 80
| ITEM
|-
| Assets
| Assets
| 90
| ASSET
|-
| Knowledge Base
| KBArticles
| 100
| KBARTICLE
|}
You can find examples of adding and updating records in the database by using the database field in the [[API Code Samples]] section.

===Account Fields===
The following table lists the most important parameters for adding/updating Account
records.
Note slight differences when adding a main account vs. adding a secondary contact.

{| class="wikitable"
|-
! '''Field Name'''
! '''Database Field Name'''
! '''Comment'''
|-
| Account REC ID
| FLDCRDCARDID
|The Account record ID (20 chars). The Account Rec ID can be taken from:
#Account Notes tab, at the bottom, rightclick the RecID field and use Copy. e.g. CRDVQYSOD1B4U4HZIQJJ
#Using ODBC to pull information from the database.
#From the Email Response when adding new Account with the API.
|-
| Account Manager
| FLDCRDASSIGNCARDID
| This field has two roles:
#When adding a main Account: The account manager should contain the ID of the Employee who is the account manager.
#When adding a secondary contact: 
This field should contain the ID of the main Account to which the secondary contacted is
added.
|-
|Company name
|FLDCRDCOMPANY
|
|-
|Contact: First & Last Name
|FLDCRDCONTACT
|
|-
| Assistant
| FLDCRDASSISTANT
|
|-
|Contract
|FLDCRDBCRECID
|The default Contract for this Account (not required)
|-
|Account Number
|FLDCRDCARDID2
|
|-
|ID
|FLDCRDCARDID3
|
|-
|Popup Message
|FLDCRDCARDMESSAGE
|
|-
| Address: Line1
| FLDCRDADDRESS1
|
|-
| Address: Line2
| FLDCRDADDRESS2
|
|-
| Address: Line3
| FLDCRDADDRESS3
|
|-
|Address: City
|FLDCRDCITY
|
|-
|Address: State
|FLDCRDCOUNTRY
|
|-
|Address: Country
|FLDCRDSTATE
|
|-
|Address: Zip
|FLDCRDZIP
|
|-
|Creation Date
|FLDCRDCREATEDATE
|Any date format, such as DD/MM/YYYY
|-
|Created by User
|FLDCRDCREATEUSERID
|Foreign Software Name which created the account
|-
|Dear
|FLDCRDDEAR
|
|-
|Department
|FLDCRDDEPARTMENT
|
|-
|Documents Store Directory
|FLDCRDDOCSFOLDER
|
|-
|E-Mail Address 1
|FLDCRDEMAIL1
|
|-
|E-Mail Address 2
|FLDCRDEMAIL2
|
|-
|Account Type
|FLDCRDENTITYKIND
|When adding a Main Account = 1 When adding a secondary contact = 5
|-
|Fax Number
|FLDCRDFAX1
|
|-
|Fax Number Extension
|FLDCRDFAXDESC1
|
|-
|File as
|FLDCRDFULLNAME
|
|-
|Type
|FLDCRDKIND
|
|-
|Last Name
|FLDCRDLASTNAME
|
|-
|Notes
|FLDCRDNOTES
|
|-
|Field
|FLDCRDPERSONID
|
|-
|Phone 1 Ext.
|FLDCRDPHNDESC1
|
|-
|Phone 2 Ext.
|FLDCRDPHNDESC2
|
|-
|Phone 3 Ext.
|FLDCRDPHNDESC3
|
|-
|Phone 4 Ext.
|FLDCRDPHNDESC4
|
|-
|Phone 1
|FLDCRDPHONE1
|
|-
|Phone 2
|FLDCRDPHONE2
|
|-
|Phone 3
|FLDCRDPHONE3
|
|-
|Phone 4
|FLDCRDPHONE4
|
|-
|Region
|Region FLDCRDREGIONCODE
|
|-
|Popup Message: Display Indication
|FLDCRDSHOWMESSAGE
|
|-
|Sub-Contact Code
|FLDCRDSUBCODE
|
|-
|Salutation
|FLDCRDSUFFIX
|
|-
|Tax1
|FLDCRDTAXCODE1
|
|-
|Tax2
|FLDCRDTAXCODE2
|
|-
|Notes
|FLDCRDNOTES
|
|-
|Title
|FLDCRDTITLE
|
|-
|Last Updated by
|FLDCRDUPDATEUSERID
|When performing updates on existing Account - pass the Foreign Software Name which performs the update.
|-
|Web Address 1
|FLDCRDURL1
|
|-
|Web Address 2
|FLDCRDURL2
|
|-
|Status
|FLDCRDUSER1
|
|-
|Field1
|FLDCRDUSER2
|
|-
|Field2
|FLDCRDUSER3
|
|-
|Field3
|FLDCRDUSER4
|
|-
|Field4
|FLDCRDUSER5
|
|}

===Ticket Fields===

The table below lists the most important Ticket parameters and behavior:

{| class="wikitable"
|-
! '''Field Name'''
! '''Database Field Name'''
! '''Comment'''
|-
| Account REC ID
| FLDTKTCARDID
|The Account record ID (20 chars). The Account Rec ID can be taken from:
#Account Notes tab, at the bottom by rightclicking the REC ID field and selecting Copy
#ODBC to pull information from the database
#The automated email response when adding a cnew Account with the API
|-
| Contact REC ID
| FLDTKTCONTACTID
|The Contact for this Account. If not provided, the main Contact for the Account is taken.
|-
| Contract REC ID
| FLDTKTBCRECID
|The Contract ID. If not supplied, will be taken from the Account's default contract.
|-
| Emp. REC ID
| FLDTKTWORKERID
|The worker ID to be linked to the Ticket. Must be an active employee. This is an optional parameter. If not passed, the system default will be used.
|-
| Priority
| FLDTKTPRIORITY
| The ticket priority. If not passed in the transaction, the default value for new Tickets will be used.
Immediate = 10 High = 20 Normal = 30 Low = 40 Not Applicable= 50
|-
| Ticket Number
| FLDTKTTICKETNO
| The Ticket number. If passed, must be an existing Ticket, and this will update the Ticket with the details in the transaction.
|-
|Description
|FLDTKTPROBLEM
|This is the Ticket Description. This is a mandatory field, which must contain text.
|-
|Ticket Type
|FLDTKTKIND
|Ticket Type (optional). The Ticket Type string should be passed. If not provided, default is used.
|-
|Source
|FLDTKTSOURCE
|
|-
|Estimated Duration Time
|FLDTKTSCHEDLENESTIM
|Estimated duration time for the Ticket in minutes.
|-
|Show Ticket in Dispatcher
|FLDTKTFORDISPATCH
|Possible values: Yes/No
|-
|Status
|FLDTKTSTATUS
|The Ticket Status (optional). 
Possible values: 
New = 100 
Pending = 200 
Scheduled = 300 
In-House Service = 400 
On-Site Service = 500 
Laboratory Service = 600 
Hold = 700 
Other = 800 
Canceled = 900 
Completed = 1000
|-
|Created by User
|FLDTKTCREATEUSER
|Should contain the external software name which created the Ticket
|-
|Due Date
|FLDTKTDUEDATETIME
|Due date for the Ticket. Should be passed in date format. e.g. MM/DD/YYYY
|-
|Resolution
|FLDTKTSOLUTION
|Ticket resolution text
|}

===Charge Fields===
The table below lists the most important Charge parameters and behavior.

Contract-price Charges have some special characteristics (see comments marked by * in
the table below):

{| class="wikitable"
|-
! '''Field Name'''
! '''Database Field Name'''
! '''Comment'''
|-
| Record ID
| FLDSLPRECID
|The Charge record ID. If provided, the existing Charge will be updated. Otherwise, this will be
added as a new Charge.
|-
| Charge Source
| FLDSLPSOURCERECID
|The Charge source is the entity for which the charge is created. 
Possible values:
*Linked Contract RecID (for Contract-price Charges). Cannot be the "System Global Contract".
**Passing the Contract RecID indicates that this is a Contract-price charge.
*Entity RecID from which the charge is created (for example when creating a charge from an Appointment or Task).
|-
| Account REC ID
| FLDSLPCARDID
|The Account record ID (20 chars). The Account REC ID can be taken from:
#Account Notes tab, at the bottom by rightclicking the REC ID field and selecting Copy
#ODBC to pull information from the database
#The automated email response when adding a new Account with the API
|-
| Employee REC ID
| FLDSLPWORKERID
| The worker record ID to be linked to the Charge. Must be an active employee. This is an optional parameter. If not passed, the system default will be used.
|-
| Charged Item
| FLDSLPITEMID
| The Item Record ID to be linked to the Charge. This is a mandatory field.
*For Contract-price Charge can be only Fixed-Price, Unit-based Item.
|-
| Contract REC ID
| FLDSLPBCRECID
| The contract record ID (must be a Contract of the Account)
|-
|Ticket REC ID
|FLDSLPTICKETID
|The Ticket ID to be linked to the Charge.
*Not relevant for Contract-price Charge
|-
|Date
|FLDSLPSLIPDATE
|The date for the Charge. This is an optional parameter. If not provided, the current date will
be used. Should be passed in date format. e.g. MM/DD/YYYY
|-
|Description
|FLDSLPDESC
|The Charge Description. If not provided, will be taken from the Item's description.
|-
|Units/Hours
|FLDSLPQUANTITY
|This is the quantity of hours/units
|-
|Adjust Amount
|FLDSLPADJUSTAMOUNT
|Discount/Markup amount. Positive number means Markup, negative number means Discount.
|-
|Adjust Percent
|FLDSLPADJUSTPERCENT
|Discount/Markup in percentage, must be between (-100) - 100. Positive number means Markup, negative number means Discount.
|-
|From Time
|FLDSLPSTARTTIME
|From time for labor Charges e.g. 12:06
*Not relevant for Contract-price Charge
|-
|To Time
|FLDSLPENDTIME
|From time for labor Charges e.g. 14:50
* Not relevant for Contract-price Charge
|-
|Price/Rate
|FLDSLPPRICE
|If not provided, the price is taken from the Item.
|-
| Billable
| FLDSLPBILLKIND
| B - Billable 
N - Not Billable 
If not provided, will be set according to the Contract type.
|-
| Billed
| FLDSLPSTAGE
| D - Draft
B - Billed
|-
| Field1
| FLDSLPUSER1
| User defined field
|-
| Create User
| FLDSLPCREATEUSER
| External software name which created the Charge
|}

===Item Fields===

The table below lists the most important Item parameters and behavior:

{| class="wikitable"
|-
! '''Field Name'''
! '''Database Field Name'''
! '''Comment'''
|-
| Record ID
| FLDSLPRECID
|The Item record ID. If provided, the existing item will be updated. Otherwise, this will be added as a new item.
|-
| Item Group
| FLDITMITEMTYPEGROUP
|The Item Group to be linked to the Charge. This is a mandatory field: 
F - Labor (Fee) 
X - Expense 
P - Part
|-
| Item Code
| FLDITMITEMNO
|The item code is a mandatory field
|-
| Item Name
| FLDITMNAME
| The item name is a mandatory field
|-
| Price Source
| FLDITMPRICESOURCE
| F - Fixed Price 
W - by Employee Rate
|-
| Price per Hour/Unit
| FLDITMUNITISHOUR
| This field indicated whether the price is unitbased or hours-based. 
Y - by Hours 
N - by Units 
This is an optional field, depending on the Item Group. For example, if the item group is Labor, and Price Source is By Employee, the value will always be by hours
|-
|Price
|FLDITMUNITPRICE
|Must be a valid numeric value
|-
|Cost
|FLDITMSTANDARDCOST
|The date for the Charge. This is an optional parameter. If not provided, the current date will
be used. Should be passed in date format. e.g. MM/DD/YYYY
|-
|Taxes
|FLDITMTAXCODE1 
FLDITMTAXCODE2 
FLDITMTAXCODE3
|You can pass up to 3 different tax codes.
|-
|Description by Name
|FLDITMDESCBYNAME
|Y - take the description from the name field 
N - take the description from the Description field
|-
|Description
|FLDITMDESC
|If not provided, the description is taken from the name.
|-
|Suspend
|FLDITMSUSPENDED
|Indicated whether this item is currently suspended: 
Y - yes 
N - no
|-
|Notes
|FLDITMNOTES
|
|-
|Field1
|FLDSLPUSER1
|User defined field
|-
|Create User
|FLDSLPCREATEUSER
|External software name which created the Charge
|-
| Created by User
| FLDTKTCREATEUSER
| Should contain the external software name which created the Ticket
|}

===History Note Fields===
The table below lists the most important History Note parameters and behavior:

{| class="wikitable"
|-
! '''Field Name'''
! '''Database Field Name'''
! '''Comment'''
|-
| Record ID
| FLDHISRECID
|The History Note record ID. If provided, the existing History Note will be updated. otherwise, this will be added as a new History Note.
|-
| Date
| FLDHISNOTEDATETIME
|Any date format, such as DD/MM/YYYY
|-
| Description
| FLDHISDESCRIPTION
| The Description text
|-
| Opportunity/Ticket/Contract
| FLDHISLINKRECID
| Link to Opportunity or Ticket or Contract
|-
| Field
| FLDHISUSER1
| User defined field
|-
| About
| FLDHISKIND
| Optional field
|-
|Employee
|FLDHISWORKERID
|The worker ID to be linked to the Ticket. Must be an active employee. This is an optional parameter. If not passed, the system default will be used.
|-
|Account
|FLDHISCARDID
|The Account record ID (20 chars). The Account Rec ID can be taken from:
#Account Notes tab, at the bottom, right-click the REC ID field and use Copy. e.g. CRDVQYSOD1B4U4HZIQJJ
#Using ODBC to pull information from the database
#From the Email Response when adding new Account with the API
|-
|Contact
|FLDHISCONTACTID
|The Contact for this Account. If not provided, the main Contact for the Account is taken.
|-
|Document
|FLDHISDOCID
|Linked Document ID, can be taken from the Document Properties window (right-click RecID and use Copy), or using the ODBC to pull information from the database.
|-
|Created by User
|FLDHISCREATEUSER
|Name of the external software which created this History Note
|}

===Asset Fields===
The table below lists the most important Asset parameters and behavior:

{| class="wikitable"
|-
! '''Field Name'''
! '''Database Field Name'''
! '''Comment'''
|-
| Asset Code
| FLDASTASSETCODE
|If an existing Asset Code is provided, then existing Asset is updated. Otherwise a new Asset is added.
|-
| Asset Type
| FLDASTASSETTYPE
|The Type field is mandatory: 
Hardware = H 
Software = S 
Other = T
|-
| Asset Name
| FLDASTNAME
|
|-
| Status
| FLDASTSTATUS
| Mandatory field. 
Active = A 
Not Active = N 
If not provided, default Active is used.
|-
| Record ID
| FLDASTRECID
| If provided, must exist in the database. Ignored if empty
|-
| Serial No.
| FLDASTSERIALNO
|
|-
|Account
|FLDASTACCRECID
|The Account which is linked to the Asset
|-
|Contact
|FLDASTCONTACTRECID
|The Contact for this Account. If not provided, the main Contact for the Account is taken.
|-
|Created by user
|FLDASTCREATEUSER
|Name of external software which created this Asset
|-
|Purchase Date
|FLDASTCUSTPURDATE
|Any date format, such as DD/MM/YYYY
|-
|Purchased From Us
|FLDASTCUSTPURFROMUS
|Possible values: Y/N. 
If not provided, default value Y is used.
|-
| Purchase Invoice #
| FLDASTCUSTPUROURINV
|
|-
| Customer PO
| FLDASTCUSTPURPO
|
|-
| Purchase Price
| FLDASTCUSTPURPRICE
|
|-
| Delivered Date
| FLDASTDELIVEDATE
|
|-
| Description
| FLDASTDESC
|
|-
| Installed By
| FLDASTINSTALBY
|
|-
| Installed Date
| FLDASTINSTALDATE
|
|-
| License Codes
| FLDASTLICENSECODE
|
|-
| License Keys
| FLDASTLICENSEKEY
|
|-
| License Notes
| FLDASTLICENSENOTES
|
|-
| Location
| FLDASTLOCATION
|
|-
| Manufacturer
| FLDASTMANUFACTURER
|
|-
| Mnf Serial No.
| FLDASTMNFSERIALNO
|
|-
| Model
| FLDASTMODEL
|
|-
| Notes
| FLDASTNOTES
|
|-
| Quantity
| FLDASTQUANTITY
| If not provided, default value of 1 is used.
|-
| Last Update By
| FLDASTUPDATEUSER
| Name of externals software which performed the update
|-
| Field1
| FLDASTUSER1
| User defined field
|-
| Field2
| FLDASTUSER2
| User defined field
|-
| Field3
| FLDASTUSER3
| User defined field
|-
| Field4
| FLDASTUSER4
| User defined field
|-
| Field5
| FLDASTUSER5
| User defined field
|-
| Date1
| FLDASTUSERDATE1
| User defined field
|-
| Number1
| FLDASTUSERNUMBER1
| User defined field
|-
| Vendor Purchased Date
| FLDASTVENDORDATEPURC
|
|-
| Vendor Invoice #
| FLDASTVENDORINVNO
|
|-
| Vendor PO
| FLDASTVENDOROURPO
|
|-
| Vendor Price
| FLDASTVENDORPRICE
|
|-
| Vendor
| FLDASTVENDORRECID
|
|-
| Vendor Serial No.
| FLDASTVENDORSERNO
|
|-
| Vendor Warranty Exp. Date
| FLDASTVENDORWARREXP
| Any date format, such as DD/MM/YYYY
|-
| Version
| FLDASTVERSION
|
|-
| Warranty/License Exp.
| FLDASTWARREXPDATE
| Any date format, such as DD/MM/YYYY
|-
| Date
|
|
|}

===Calendar Fields===
The table below lists the most important Calendar parameters and behavior:

{| class="wikitable"
|-
! '''Field Name'''
! '''Database Field Name'''
! '''Comment'''
|-
| Record ID
| FLDEVTRECID
|The Appointment/Task record ID. If provided, the existing entity will be updated. Otherwise, this
will be added as a new Appointment/Task.
|-
| Event Type
| FLDEVTWRITETOID
|The Event type is a mandatory field. 
Appointment = 1 
Task = 2
|-
| Employee
| FLDEVTWORKERID
| The Task/Appointment owner (for private events)
|-
| Private: User
| FLDEVTPRIVATEID
| Possible values: Y/N 
If an Employee was set, this field must be Y
|-
| Account
| FLDEVTCARDID
| The Account record ID (20 chars). The Account REC ID can be taken from:
#Account Notes tab, at the bottom by rightclicking
the REC ID field and selecting Copy
#ODBC to pull information from the database
#The automated email response when adding a
new Account with the API
|-
| Contact
| FLDEVTCONTACTID
| The Contact for this Account. If not provided, the main Contact for the Account is taken.
|-
|Document
|FLDEVTDOCID
|Linked Document ID, can be taken from the Document Properties window (right-click RecID and use Copy), or using the ODBC to pull information from the database.
|-
|Done Indication
|FLDEVTDONE
|Possible values: Y/N
|-
|Date
|FLDEVTEVENTDATE
|The Appointment/Task date is a mandatory field of Any date format, such as DD/MM/YYYY. If not
provided, the current date will be used.
|-
|Description
|FLDEVTFREETEXT
|
|-
|Time: Start
|FLDEVTFROMTIME
|Mandatory field
|-
| Time: End
| FLDEVTTOTIME
| Relevant only for Appointments. If this parameter is not provided, 30 min. interval from Start Time is used.
|-
| Opportunity/Ticket
| FLDEVTLINKRECID
| Linked Ticket/Opportunity/Contract/Asset
|-
| Field1
| FLDEVTFAMILY
| User Defined field
|-
| Field2
| FLDEVTACTION
| User Defined field
|-
| Field3
| FLDEVTPLACE
| User Defined field
|-
| Field4
| FLDEVTPLACE1
| User Defined field
|-
| Field5
| FLDEVTPLACE2
| User Defined field
|-
| Created by User
| FLDEVTCREATEUSERID
| Name of external software which created the event
|-
| Last Update: By User
| FLDEVTUPDATEUSER
| Name of external software which updated the
event
|}

===Opportunity Fields===
The table below lists the most important Opportunity parameters and behavior:

{| class="wikitable"
|-
! '''Field Name'''
! '''Database Field Name'''
! '''Comment'''
|-
| Record ID
| FLDOPPRECID
| The Opportunity record ID. If provided, the existing Opportunity will be updated. Otherwise, this will be added as a new Opportunity.
|-
| Opportunity Name
| FLDOPPNAME
| Mandatory field.
|-
| Opportunity ID
| FLDOPPUSERID
| Optional (Oppty ID)
|-
| Account
| FLDOPPCARDID
| The Account record ID (20 chars). The Account REC ID can be taken from:
#Account Notes tab, at the bottom by right-clicking the REC ID field and selecting Copy
#ODBC to pull information from the database
#The automated email response when adding a new Account with the API
|-
| Contact
| FLDEVTCONTACTID
| The Contact for this Account. If not provided, the main Contact for the Account is taken.
|-
| Source
| FLDOPPSOURCE
|
|-
|Document
|FLDEVTDOCID
|Linked Document ID, can be taken from the Document Properties window (right-click RecID and use Copy), or using the ODBC to pull information from the database.
|-
|Done Indication
|FLDEVTDONE
|Possible values: Y/N
|-
|Close Date
|FLDOPPCLOSEDATE
|
|-
|Manager
|FLDOPPWORKERID
|The Manager's REC ID
|-
|Open Date
|FLDOPPOPENDATE
|
|-
| Close By Date
| FLDOPPESTDATE
| Opportunity must be closed by this date
|-
| Amount
| FLDOPPAMOUNT
|
|-
| Probability %
| FLDOPPPROBABILITY
|
|-
| Stage
| FLDOPPSTAGE
|
|-
| Status
| FLDOPPSTATUS
|
|-
| Closing Amount
| FLDOPPCLOSEAMOUNT
|
|-
| Description
| FLDOPPDESCRIPTION
|
|-
| Opportunity Type
| FLDOPPKIND
|
|-
| Opportunity Reason
| FLDOPPREASON
|
|-
| Note
| FLDOPPNOTES
|
|-
| Territory
| FLDOPPREGION
|
|-
| Field1
| FLDEVTFAMILY
| User Defined field
|-
| Field2
| FLDEVTACTION
| User Defined field
|-
| Field3
| FLDEVTPLACE
| User Defined field
|-
| Created by User
| FLDEVTCREATEUSERID
| Name of external software which created the event
|-
| Last Update: By User
| FLDEVTUPDATEUSER
| Name of external software which updated the event
|}

===Document Fields===
The table below lists the Document parameters and behavior:

{| class="wikitable"
|-
! '''Field Name'''
! '''Database Field Name'''
! '''Comment'''
|-
| Record ID
| FLDDOCRECID
| The Document record ID. If provided, the existing Document will be updated. Otherwise, this will be added as a new Document.
|-
| Document Date
| FLDDOCDOCDATE
| The date for the Document. This is an optional parameter. If not provided, or if the value is illegal, the current date will be used. Should be passed in date format. e.g. MM/DD/YYYY
|-
| Subject
| FLDOPPUSERID
|
|-
| Linked Record
| FLDDOCLINKRECID
| The RECID of a linked object. Each Document can be linked to one of the following objects:
*Ticket
*Contract
*Opportunity
*Knowledge Base Article
*Asset
The Record ID (20 chars) can be taken from:
#Object's Notes tab, at the bottom by right-clicking the REC ID field and selecting Copy
#ODBC to pull information from the database
#The automated email response when adding a new object with the API.
|-
| Account Rec ID
| FLDDOCCARDID
| The Account record ID (20 chars). The Account REC ID can be taken from:
#Account Notes tab, at the bottom by right-clicking the REC ID field and selecting Copy
#ODBC to pull information from the database
#The automated email response when adding a new Account with the API
|-
| Contact REC ID
| FLDDOCCONTACTID
| The Contact for this Account. If not provided, the main Contact for the Account is taken.
|-
|Field1
|FLDDOCTRANSPORT
|User Defined field
|-
|Field2
|FLDDOCFOLDER
|User Defined field
|-
|Field3
|FLDDOCUMENTPLACE
|User Defined field
|-
|File Path + File name
|FLDDOCDOCUMENTNAME
|The Document path
|-
|Category
|FLDDOCTREEID
|The category record ID should be taken from the database table called TreeTbl which contains the Category tree
|-
| Employee REC ID
| FLDDOCWORKERID
| The worker record ID to be linked to the Document. Must be an active employee. This is an optional parameter. If not passed, the system default will be used.
|-
| Created by User
| FLDDOCCREATEUSER
| Name of external software which created the document
|-
| Last Update: By User
| FLDDOCUPDATEUSER
| Name of external software which updated the document
|}

===Knowledge Base Article Fields===
The table below lists the Knowledge Base Article parameters and behavior:

{| class="wikitable"
|-
! '''Field Name'''
! '''Database Field Name'''
! '''Comment'''
|-
| Record ID
| FLDKBARECID
| The Article record ID. If provided, the existing Article will be updated. Otherwise, this will be added as a new Article.
|-
| Document Date
| FLDKBACREATEDATE
| The date for the Document. This is an optional parameter. If not provided, or if the value is illegal, the current date will be used. Should be passed in date format. e.g. MM/DD/YYYY
|-
| Title
| FLDKBATITLE
|
|-
| Problem
| FLDKBAPROBLEM
|
|-
| Solution
| FLDKBASOLUTION
|
|-
| Status
| FLDKBASTATUS
| Possible values:
*DRAFT = 'D'
*PUBLISHED = 'P'
*OBSOLETE = 'O'
|-
|Category
|FLDKBACATEGORY
|
|-
|Public
|FLDKBAISPUBLIC
|Is the Document public. 
Possible values: 
*'Y' = Yes
*'N' = No
|-
|Created by User
|FLDDOCCREATEUSER
|Name of external software which created the document
|-
|Last Update: By User
|FLDDOCUPDATEUSER
|Name of external software which updated the document
|}

===Error Codes Description===
These error codes are returned when calling the CmtGetDescriptionByStatus function: 
'''1000''' CmtDbEng.dll not found. 
'''1001''' Invalid value for the Data Kind value. 
'''1002''' Invalid DATA buffer received. Make sure you have allocated the buffer correctly and
that you have passed the correct buffer length. 
'''1003''' Invalid MAP buffer received. Make sure you have allocated the buffer correctly and
that you have passed the correct buffer length. 
'''1004''' Invalid REC ID buffer received. Make sure you have allocated the buffer correctly
and that you have passed the correct buffer length. 
'''1005''' Invalid LOG buffer received. Make sure you've allocated the buffer correctly and
that you've passed the correct buffer length. 
'''1006''' Invalid REC ID buffer received. It should be at least 20 characters. 
'''1007''' Invalid external software name received. Specify a unique name that identifies your
software. 
'''1008''' Cannot process the transaction. Make sure to call the INIT procedure at least once
prior to sending transactions for processing. 
'''1009''' Path specified for Commit DB folder not found. 
'''1010''' Path specified for Commit DB folder found, but its contents do not reflect a valid DB
folder. 
'''1011''' The RED ID received for the employee/user was not found in Commit, is invalid or is
related to an inactive employee record. 
'''1012''' Error registering software. 
'''1013''' Software name is missing. Make sure you specify a name that identifies your
software. 
'''1014''' Software name is less than 3 characters long. Make sure you enter a software name
that has 3 to 15 characters. 
'''1015''' Software name is too long. Make sure your software name has 3 to 15 characters. 
'''1100''' Database access error. 

General error codes, returned when calling the functions CmtGetDescriptionByCode: 
'''50000''' The data is not correct for its type. 
'''50001''' The field value has been truncated due to the field length in the database. 
'''50002''' The insert operation Failed because the REC ID already existed in the database. 
'''50003''' Failed to update Record since it is being updated by another user. 
'''50103''' Illegal REC ID. 
'''50104''' REC ID Creation failed. 
'''50105''' Illegal Sub-Contact REC ID. 
'''50106''' Illegal Contract REC ID. 
'''50107''' Illegal Employee REC ID. 
'''50108''' Illegal Ticket REC ID. 
'''50109''' Illegal Account REC ID. 
'''50110''' Illegal data for that Contract. 
'''50111''' This Employee is not active. 
'''50112''' Illegal Document REC ID. 
'''50113''' Illegal linked object REC ID. 
'''50114''' Employee not found. 
'''50115''' Some mandatory fields have no values. 
'''51000''' Illegal kind of Account entity. 
'''51001''' Account Manager not found. 
'''51002''' The REC ID of the Account Manager is illegal. 
'''51003''' Illegal tax code. 
'''51004''' This code does not exist in Commit. 
'''52000''' Illegal kind of event. 
'''52001''' Illegal start time. 
'''52002''' Illegal end time. 
'''52003''' Illegal event date. 
'''52004''' The field Reminder1 has Illegal Value. 
'''52005''' The amount in the field has an illegal value. 
'''52006''' The Field Remider1:Units has Illegal Value. 
'''52007''' The Field Remider2:Active has Illegal Value. 
'''52008''' The Field Remider2:Amount has Illegal Value. 
'''52009''' The Field Remider2:Units has Illegal Value. 
'''52010''' Illegal employee REC ID. 
'''52011''' Error occurred while updating the Task/Appointment employee field. 
'''54000''' Illegal Ticket open date. 
'''54001''' Illegal Ticket close date. 
'''54002''' Illegal Ticket code area. 
'''54004''' Illegal Ticket priority. 
'''54005''' Illegal Ticket status. 
'''54006''' The Ticket Account was not found in the database. 
'''54007''' The Ticket Account Manager was not ound in the database. 
'''54008''' This code does not exist in Commit. 
'''54009''' This code does not exist in Commit. 
'''54010''' This code does not exist in Commit. 
'''54011''' This code does not exist in Commit. 
'''54012''' This code does not exist in Commit. 
'''55000''' Illegal charge date. 
'''55001''' Illegal charge REC ID. 
'''55002''' Illegal start date. 
'''55003''' Illegal start time. 
'''55004''' Illegal amount entered for hours. 
'''55005''' Illegal quantity. 
'''55006''' Illegal price. 
'''55007''' Illegal total. 
'''55008''' Illegal value in the Adjust Amount field. 
'''55009''' Illegal value in the Adjust Percent. 
'''55010''' The Discount/Markup field has an illegal value. 
'''55011''' Illegal value in the Adjust Kind field. 
'''55012''' Illegal bill total. 
'''55013''' You can not create a charge for a suspended item. 
'''55014''' Item was not found in Commit. 
'''55015''' This code does not exist in Commit. 
'''55016''' This code does not exists in Commit. 
'''55017''' This Code does not exist in Commit. 
'''55018''' This Code does not exist in Commit. 
'''55019''' This Code does not exist in Commit. 
'''55020''' This Code does not exist in Commit. 
'''55021''' This Code does not exist in Commit. 
'''56000''' Illegal item code. 
'''56001''' The field that indicates the item group type has an illegal value. 
'''56002''' The field that indicates if the Item is suspended has an illegal value. 
'''56003''' Illegal value of The field that indicate if the item is suspended. 
'''56004''' Mismatch found between the fields price and price source. 
'''56005''' Illegal cost. 
'''56006''' Mismatch found between the fields cost and item group type. 
'''56007''' The field that indicates if the charge is by unit or by hours has an illegal value. 
'''56008''' Illegal value in the Description. 
'''56009''' The field that indicates the item type has an illegal value. 
'''57000''' This Code does not exist in Commit. 
'''58000''' Illegal date time. 
'''58001''' The Description field was not found. 
'''58002''' The field kind was not found. 
'''58003''' The Account member was not found. 
'''59000''' This code does not exists in Commit. 
'''59001''' This Code does not exist in Commit. 
'''59002''' This Code does not exist in Commit. 
'''59003''' This Code does not exist in Commit. 
'''59004''' This Code does not exist in Commit. 
'''59005''' This Code does not exist in Commit. 
'''60000''' Invalid web user record ID number. 
'''60001''' This customer web user is not active. 
'''60002''' This user is not a customer. 

==See Also==
*[[Commit API Developers Guide]]
*[[API Code Samples]]
[[Category:User Manuals]]
[[Category:Integration]]

__NOTOC__

Report Customization

2010-02-23T12:49:27Z

Reno:

{{customization}}
CommitCRM reports can be customized in two ways:
#'''Add your own header''' - You can set/modify a textual header (with your company name, etc.) for all reports at once by selecting Tools > Options > Reports tab > click on Edit Header.
#'''Designing reports data and layout''' –
#*To customize CommitCRM reports, open the Reports window, select the report you want to customize, select '''Copy''' from the toolbar and enter your new report name. The copied report will be selected. Select the '''Design''' button from the toolbar, and the report designer will open.
#*To add a '''new data field''' to a custom report, select a '''DBText''' button from the report designer toolbar and place it where desired in the report layout. With the newly created field selected, select the appropriate Data Field from the drop down list on the toolbar, which is located on the upper-left corner. If you want to add a Title, select the '''Label''' button from the toolbar, place it on the report and write the title in the text area on the windows toolbar, which is located on the upper-left corner as well.
#*To view your customized reports, click the Custom Reports radio button on the Reports window.

Make sure to watch the [http://www.commitcrm.com/videos/commit_report_designer_tutorial_video.htm CommitCRM Report Designer Tutorial] which will guide you through a basic report design process and show you how you can change the report layout and add new fields to the report.

'''For more information; see the [[Report_Designer_User_Guide|Report Designer User Guide]].'''

==See Also==
*[[Reports FAQ]]

[[Category:Customization]]
[[Report_Designer_User_Guide|Report Designer User Guide]]