General System Design

AdvantageME Customer: VCC Customer (VCC)

Document Review and Change Summary
Version/
Review Date / Brief Summary of Changes From Prior Version / Changed By / Document
Reviewers
Version 1.0
12/05/11 /
  • Original
/ Joo Kook
Version 1.1
12/07/11 /
  • Removed VCC_AD_1099 section and updated attributes per discussion with Maine
/ Joo Kook / Utkarsh Pansuriya
Version 1.2
12/13/11 /
  • Updated DOC_CAT, DOC_TYP, DOC_VERS_NO, DFLT_AD_TYP and AD_AUTO_GEN_FL data types
  • Updated sample XML to include DOC_REC_DT_DC and EXT_DOC_DSCR fields
/ Joo Kook
Version 1.3
12/19/11 /
  • Updated attributes notes section to require capitalization for alphabetic values
/ Joo Kook
Version 1.4
1/4/2012 /
  • Updated VCC_DOC_VCUST with optional fields INT_ACCT_FL and ALIAS_NM
  • Updated VCC_DOC_AD with optional fields CN_AUTO_GEN_FL, PRIN_CNTAC, ACORSPD_TYP, EMAIL_AD, and CNTAC_PH_NO
/ Joo Kook
1/12/2012 /
  • Updated Conditional Requirements, Example of Canadian Province ZIP, and Notes for INT_ACCT_FL
/ Phillip Platt

Table of Contents

1.Overview

1.1.Document Definitions and Naming Conventions

1.2.Document Usage

1.3.Logical Document Component Structure

AdvantageME VCC Document Structure

2.Publishable Specification

2.1.Transaction Layout: VCC

2.1.1Document Prefixes

2.1.2Data Repository

2.1.3DOC_ID Standard

2.1.4VCC AMS_DOC_EXPORT_XML_FILE root element attributes

2.1.5VCC AMS_DOCUMENT root element attributes

2.1.6VCC Document Component: VCC_DOC_HDR

2.1.7VCC Document Component: VCC_DOC_VCUST

2.1.8VCC Document Component: VCC_DOC_AD

2.1.9VCC Document Component: VCC_DOC_CUSTACC

2.1.10VCC Document Component: VCC_DOC_CERT

2.1.11VCC Customer XML Example

1.Overview

1.1.Document Definitions and Naming Conventions

This section describes/defines the DTD naming conventions applied in this document.

Transaction Layout Definitions

  • Attribute – The name of the data element in the database, as well as the name of the XML tag.
  • Caption – The label on the User Interface that defines the data element.
  • Description – A textual description of the data element.
  • R/C – Required/Conditional. Required specifies that the data element is required by the interface for the transaction to successful submit. Conditional means that specified conditions must be adhere to by the interface for the transaction to successful submit. No value specifies that the data element is optional by the interface for the transaction to submit.
  • Type – The data type of the data element.
  • VarChar – Variable Character text. Alphanumeric data.
  • Byte – Unsigned character.
  • Char – Character. Fixed length alphanumeric text, required to meet the exact specified size.
  • Date – Date Format YYYY-MM-DD
  • Decimal – Numeric value with a specified decimal position (9,3) = 999999999.999
  • Boolean –True/False. True conditions = “true”, False conditions = “false”.
  • Memo – Alphanumeric Text with a maximum of 1500 characters.
  • Currency – Numeric, with two decimal positions. Format 9999.99.
  • Integer – Numeric value, a whole number.
  • Long - Numeric value, a long whole number.
  • Size – The (numeric) size of the data element
  • AdvantageME Notes – Notes specific to the AdvantageME data element.

XML Definitions and Conventions

  • Root - The upgraded MFASIS XML file and document root declaration identify the required root elements that must be contained for the XML file or document (transaction) to load into MFASIS. The upgraded MFASIS XML file must contain a single root element that contains specified attributes, at the file level. Each document transaction contained within the XML file must also contain a root element that contains the specified attributes, at the document level.
  • Attributes - Attributes are name-value pairs that occur inside start-tags after the element name.
  • Elements - Elements are the most common form of markup. Delimited by angle brackets, most elements identify the nature of the content they surround. Elements normally begins with a start-tag, <element>, and ends with an end-tag, </element>.
  • CDATA Tags - In a document, CDATA instructs the parser to ignore (most) markup characters. Between the start of the section, <![CDATA[ and the end of the section, ]]>, all character data is passed directly to the application, without interpretation. Elements, entity references, comments, and processing instructions are all unrecognized and the characters that comprise them are passed “literally” to the application.

1.2.Document Usage

Within the State of Maine financial system, departments process VCC documents to create Vendor Customer records. The VCC document adds new records to the Vendor/Customer (VCUST) table and the Customer Account Options (CACT) table.

Parts of the Vendor/Customer Creation Document:

The Vendor/Customer Creation document has 5 components. These components will be populated through the State’s VCCCustomer interface:

Header- Contains document description information.

Vendor/Customer– Is the main data entry point in which you will enter information associated with a customer. Fields in this section include vendor/customer code, organization type, company name, taxpayer identification number and other disbursement and EFT information fields.

Address– Contains address as well as contact information related to the customer.

Customer Account– Contains billing information for the customer, such as billing profile and collection cycle.

Certification– Contains the active and approval status information for the customer.

1.3.Logical Document Component Structure

AdvantageME VCC Document Structure

2.Publishable Specification

2.1.Transaction Layout: VCC

Action Code (OE) / Component Description
Document Component / AMS_DOC_EXPORT_XML_FILE / R / XML file root element.
AMS_DOCUMENT / R / Document root element.
VCC_DOC_HDR / R / Lists description information associated with the customer.
VCC_DOC_VCUST / R / Lists customer information such as legal name and various options related to the customer.
VCC_DOC_AD / R / Lists the address and contact information for the customer.
VCC_DOC_CUSTACC / R / Lists the billing related information for the customer.
VCC_DOC_CERT / R / Lists the active and approval status of the customer.

R – Required

CR – Conditionally Required: Based on the entry from another tag, some tags are either required or prohibited (i.e. First Name and Last Name become required if the Org Type is set to Individual. First Name and Last Name become prohibited if the Org Type is set to Company).

O – Optional

NOTE:Every field listed in the following tables MUST beincluded in the XML script. For this purpose, “null” may be a valid value (see the XML sample attached). Alphabetic values must be capitalized as listed in the “AdvantageME Notes” column.

2.1.1Document Prefixes

In order to identify the interfaces by agency and type, the following codes have been assigned. References will be made to these codes throughout the mapping document:

External Interface / File Prefix / Document Creator ID
TBD / TBD / TBD / TBD

2.1.2Data Repository

A central repository will exist for each interface partner.The server location is som-isa1asmom02.som.w2k.state.me.us. Security permissions will be such that only the agency partner specified can access the file structure(s) assigned to them. Note: Advantage technical personnel and OIT systems personnel will have permission to access all folders.

Each agency will PUSH their CR files to corresponding inbound folder (see below). A copy of the file is automatically archived for historical purposes.

The directory structure will look similar to the below:

som-isa1asmom02.som.w2k.state.me.us / \Archive
som-isa1asmom02.som.w2k.state.me.us / \Customer
som-isa1asmom02.som.w2k.state.me.us / \Inbound / \INTFAGR / \AGR0325CR1.xml
\AGR0325CR1.inf
som-isa1asmom02.som.w2k.state.me.us / \Outbound
som-isa1asmom02.som.w2k.state.me.us / \Vendor

2.1.3DOC_ID Standard

There will be no user-specified prefix for the DOC_ID and will be assigned through the auto-numbering functionality.

2.1.4VCCAMS_DOC_EXPORT_XML_FILE root element attributes

Attribute / Caption / Description / R/C / Type / Size / AdvantageME
Notes
VERSION / Version of the XML file / R / VarChar / Default Value: ”1”
This field is required for documentation purpose does not have any impact on the interface.
EXPORT_DATE / Export date and time. / R / VarChar / Format :yyyy-mm-dd hh:mm:ss
Default Value: Current System date
This field is required for documentation purpose does not have any impact on the interface.

Page 1 of 23

MFASIS-CR-GSD-07-10-2007

2.1.5VCCAMS_DOCUMENT root element attributes

Attribute / Caption / Description / R/C / Type / Size / AdvantageME
Notes
DOC_CAT / Document Category / The category in which the document is located. / R / VarChar / 8 / “VCUST”
Must be capitalized.
DOC_TYP / Document Type / The type of document, defined in the Document Type table. Each document code must be assigned a document type. / R / VarChar / 8 / “VCC”
Must be capitalized.
DOC_CD / Document Code / The alpha-numeric identification code assigned to the document on the Document Control table. / R / VarChar / 8 / “VCC”
Must be capitalized.
DOC_DEPT_CD / Department Code / The department code assigned to this document. / R / VarChar / 4 / Must be valid on R_DEPT table
DOC_UNIT_CD / Unit Code / The unit code associated with this document. / R / VarChar / 4 / Must be valid on R_UNIT table
DOC_ID / Document Id / The document ID to identify this document. / R / VarChar / 20 / Null
Will be generated via auto-numbering functionality.
DOC_VERS_NO / Document Version Number / The version number assigned to this document. The version is incremented with each modification draft and after with a cancellation. / R / Number / 10 / 1
AUTO_DOC_NUM / Automatic document numbering is turned on. / R / VarChar / 3 / “true”
DOC_IMPORT_MODE / Document Import Mode / The import mode determining the phase of the document on import. Will be set to “OE” for Original Entry. / R / VarChar / 4 / “OE”
Must be capitalized.

2.1.6VCC Document Component: VCC_DOC_HDR

VCC_DOC_HDR
Attribute / Caption / Description / R/C / Type / Size / AdvantageME
Notes
DOC_CAT / Document Category / The category in which the document is located. / R / VarChar / 8 / Same as in AMS_DOCUMENT
DOC_TYP / Document Type / The type of document, defined in the Document Type table. Each document code must be assigned a document type. / R / VarChar / 8 / Same as in AMS_DOCUMENT
DOC_CD / Document Code / The alpha-numeric identification code assigned to the document on the Document Control table. Each document code must be unique within the application. The document code is a required field when creating a new document. It also may be selection criteria on a parameter table, a key to a specific business rule on a control table, or the document code recorded on a historical record. / R / VarChar / 8 / Same as in AMS_DOCUMENT
DOC_DEPT_CD / Department Code / The department code assigned to this document. / R / VarChar / 4 / Same as in AMS_DOCUMENT
DOC_ID / Document Id / The document code and number that is either manually assigned or automatically generated by the system if you do not enter this information. The version number is assigned automatically. Duplicate document identification numbers are not allowed in the system. / R / VarChar / 20 / Same as in AMS_DOCUMENT
DOC_VERS_NO / Document Version Number / The version number assigned to this document. The version is incremented with each modification draft and after with a cancellation. / R / Number / 10 / Same as in AMS_DOCUMENT
DOC_CREA_USID / The user identification code assigned by the system for the user creating this document. / R / VarChar / 20 / TBD
DOC_UNIT_CD / Unit Code / The unit code associated with this document. / R / VarChar / 4 / Same as in AMS_DOCUMENT
DOC_REC_DT_DC / Record Date / The record date manually entered on the document header. If not manually entered, the date becomes the one when the document was submitted successfully. / O / Date / yyyy-mm-dd
DOC_DSCR / Document Description / The description associated with the document. / O / VarChar / 60 / "CUSTOMER INTERFACE"
Must be capitalized.
DSCR_EXT / Extended Description / A free-form text field that will hold a large volume of information to be associated with a document component. It is larger than the regular description field, but still limited unlike attachments / O / VarChar / 1500
DOC_NM / Document Name / Name for the document. / O / VarChar / 60 / "CUSTOMER INTERFACE"
Must be capitalized.

2.1.7VCC Document Component: VCC_DOC_VCUST

VCC_DOC_VCUST
Attribute / Caption / Description / R/C / Type / Size / AdvantageME
Notes
DOC_CAT / Document Category / The category in which the document is located. / R / VarChar / 8 / Same as in AMS_DOCUMENT
DOC_TYP / Document Type / The type of document, defined in the Document Type table. Each document code must be assigned a document type. / R / VarChar / 8 / Same as in AMS_DOCUMENT
DOC_CD / Document Code / The alpha-numeric identification code assigned to the document on the Document Control table. Each document code must be unique within the application. The document code is a required field when creating a new document. It also may be selection criteria on a parameter table, a key to a specific business rule on a control table, or the document code recorded on a historical record. / R / VarChar / 8 / Same as in AMS_DOCUMENT
DOC_DEPT_CD / Department Code / The department code assigned to this document. / R / VarChar / 4 / Same as in AMS_DOCUMENT
DOC_UNIT_CD / Unit Code / The unit code associated with this document. / R / VarChar / 4 / Same as in AMS_DOCUMENT
DOC_ID / Document Id / The document code and number that is either manually assigned or automatically generated by the system if you do not enter this information. The version number is assigned automatically. Duplicate document identification numbers are not allowed in the system. / R / VarChar / 20 / Same as in AMS_DOCUMENT
DOC_VERS_NO / Document Version Number / The version number assigned to this document. The version is incremented with each modification draft and after with a cancellation. / R / Number / 10 / Same as in AMS_DOCUMENT
VEND_CUST_CD / Vendor/Customer / The unique identifier assigned to the vendor/customer. In ADVANTAGE Financial, a vendor can also be a customer, allowing you to enter information only one time when a particular contact is both a vendor (payable) and a customer (receivable). On a GAX document, these will be all the vendors. / R / VarChar / 20 / Department code + alpha numeric (e.g. 10A11AB00001)
Must be capitalized.
ORG_TYP / Organization Type / The type of the organization. If this field is Individual, then the Company Name field must be blank and the First and Last Name fields will be required. If this field is Company, then the First, Middle, and Last Name fields must be blank and the Company Name field will be required. If this field is blank, then the Company Name and First Name or Middle Name, or Last Name fields may not be populated at the same time. / R / Number / 10 / 1 = Individual
2 = Company
FRST_NM / First Name / The first name of the vendor/customer. This field is only required if the Organization Type is set to ‘Individual’. / C / VarChar / 14 / Required if ORG_TYP = 1.
e.g. “JOHN”
Must be capitalized.
MID_NM / Middle Name / The middle name of the vendor/customer. This field is optional and can only be entered if the Organization Type is set to ‘Individual’. / C / VarChar / 14 / Optional if ORG_TYP = 1.
e.g. “LEE”
Must be capitalized.
LAST_NM / Last Name / The last name of the vendor/customer. This field is only required if the Organization Type is set to ‘Individual’. / C / VarChar / 30 / Required if ORG_TYP = 1.
e.g. "BAKER”
Must be capitalized.
COMP_NM / Company Name / This is the legal name of the organization. This field is only required if the Organization Type is set to ‘Company’. / C / VarChar / 60 / Required if ORG_TYP = 2.
e.g. “BAKER COMPANY”
Must be capitalized.
ALIAS_NM / Alias/DBA / This is the alias or “doing business as” name of the organization. / O / VarChar / 60
INT_ACCT_FL / Internal Account / This is the flag to indicate an organization as an internal account. / O / VarChar / 3 / true/false

Page 1 of 23

MFASIS-CR-GSD-07-10-2007

2.1.8VCC Document Component: VCC_DOC_AD

VCC_DOC_AD
Attribute / Caption / Description / R/C / Type / Size / AdvantageME
Notes
DOC_CAT / Document Category / The category in which the document is located. / R / VarChar / 8 / Same as in AMS_DOCUMENT
DOC_TYP / Document Type / The type of document, defined in the Document Type table. Each document code must be assigned a document type. / R / VarChar / 8 / Same as in AMS_DOCUMENT
DOC_CD / Document Code / The alpha-numeric identification code assigned to the document on the Document Control table. Each document code must be unique within the application. The document code is a required field when creating a new document. It also may be selection criteria on a parameter table, a key to a specific business rule on a control table, or the document code recorded on a historical record. / R / VarChar / 8 / Same as in AMS_DOCUMENT
DOC_DEPT_CD / Department Code / The department code assigned to this document. / R / VarChar / 4 / Same as in AMS_DOCUMENT
DOC_UNIT_CD / Unit Code / The unit code associated with this document. / R / VarChar / 4 / Same as in AMS_DOCUMENT
DOC_ID / Document Id / The document code and number that is either manually assigned or automatically generated by the system if you do not enter this information. The version number is assigned automatically. Duplicate document identification numbers are not allowed in the system. / R / VarChar / 20 / Same as in AMS_DOCUMENT
DOC_VERS_NO / Document Version Number / The version number assigned to this document. The version is incremented with each modification draft and after with a cancellation. / R / Number / 10 / Same as in AMS_DOCUMENT
AD_TYP / Address Type / Indicates the type of address. Options are Billing, Payment, Procurement and Account Administrator. / R / VarChar / 2 / “BI”
Must be capitalized.
DFLT_AD_TYP / Default Address Type / Indicates if this address is the default address for a given address type. Only one address per address type can be marked as the default record. The record marked as default is used on documents and other processes to infer an address/contact when one is not specified. / R / VarChar / 3 / “true”
If there are multiple address records, then only first one is set to “true” and the rest are set to “false”
AD_AUTO_GEN_FL / Auto Generation Flag / If selected, then Advantage will automatically generate an Address ID for the record. The Address ID begins with AD and is followed by 3 characters using the next increment on the Address table for the associated Headquarters. / R / VarChar / 3 / “true”
STR_1_NM / Street 1 / The first line of the street address. / R / VarChar / 75 / e.g. “100 MAIN ST”
Must be capitalized.
STR_2_NM / Street 2 / The second line of the street address. / O / VarChar / 75
CITY_NM / City / The city name associated with the address. / R / VarChar / 75 / e.g. “AUGUSTA”
Must be capitalized.
ST / State / The State or Province associated with the address. / R / VarChar / 2 / Value should exist on the State/Province table.
e.g. “ME”
Must be capitalized.
ZIP / ZIP Code / The zip code associated with the address. / R / VarChar / 10 / e.g. “04330” (Augusta ZIP) or “E4L1G6” (Canadian Province)
VOICE_PH_NO / Phone / The telephone number associated with the contact. / R / VarChar / 30 / e.g. “207-287-1000”
CN_AUTO_GEN_FL / Auto Generate / If selected, then Advantage will automatically generate a Contact ID for the record. / O / VarChar / 3 / e.g. “true”
PRIN_CNTAC / Principal Contact / Contact associated with the address entry. / O / VarChar / 60
CNTAC_PH_NO / Phone / The telephone number associated with the contact. / O / VarChar / 30
ACORSPD_TYP / Correspondence Type / Options are Email, Fax, or Postal Service. / O / Number / 10
EMAIL_AD / Email / Email address associated with the contact / O / VarChar / 100

2.1.9 VCC Document Component: VCC_DOC_CUSTACC

VCC_DOC_CUSTACC
Attribute / Caption / Description / R/C / Type / Size / AdvantageME
Notes
DOC_CAT / Document Category / The category in which the document is located. / R / VarChar / 8 / Same as in AMS_DOCUMENT
DOC_TYP / Document Type / The type of document, defined in the Document Type table. Each document code must be assigned a document type. / R / VarChar / 8 / Same as in AMS_DOCUMENT
DOC_CD / Document Code / The alpha-numeric identification code assigned to the document on the Document Control table. Each document code must be unique within the application. The document code is a required field when creating a new document. It also may be selection criteria on a parameter table, a key to a specific business rule on a control table, or the document code recorded on a historical record. / R / VarChar / 8 / Same as in AMS_DOCUMENT
DOC_DEPT_CD / Department Code / The department code assigned to this document. / R / VarChar / 4 / Same as in AMS_DOCUMENT
DOC_UNIT_CD / Unit Code / The unit code associated with this document. / R / VarChar / 4 / Same as in AMS_DOCUMENT
DOC_ID / Document Id / The document code and number that is either manually assigned or automatically generated by the system if you do not enter this information. The version number is assigned automatically. Duplicate document identification numbers are not allowed in the system. / R / VarChar / 20 / Same as in AMS_DOCUMENT
DOC_VERS_NO / Document Version Number / The version number assigned to this document. The version is incremented with each modification draft and after with a cancellation. / R / Number / 10 / Same as in AMS_DOCUMENT
BPRO_CD / Billing Profile / The identification code assigned to the billing profile. / R / VarChar / 5 / Should exist on the BPRO table.
e.g. “BPC1”
Must be capitalized.
DEPT_CD / Dept / An identification code assigned to a central organizational level element where the decentralized structure is set. The department field may be used as an input field on a document, an additional key to another chart of account element, a selection criteria on a parameter table, a key to a specific business rule on a control table, a field to be inferred on a document, or the department value on a historical record. / R / VarChar / 4 / Should exist on the DEPT table
UNIT_CD / Unit / The unit code associated with the billing profile. / R / VarChar / 4 / Should exist on the UNIT table.
Recommend using “ALL”
BILL_LOC_CD / Billing Location / The location where the receivable is to be sent. Required if the billing type is Invoices, Statements, or Both. Valid values are: Customer Only, Third Party Only, Third Party with Customer Copy, Parent Address Only, or Parent Address with Customer Copy. Default is Customer Only. / R / VarChar / 2 / Recommend use “CO” = Customer Only
Must be capitalized.

2.1.10 VCC Document Component: VCC_DOC_CERT

VCC_DOC_CERT
Attribute / Caption / Description / R/C / Type / Size / AdvantageME
Notes
DOC_CAT / Document Category / The category in which the document is located. / R / VarChar / 8 / Same as in AMS_DOCUMENT
DOC_TYP / Document Type / The type of document, defined in the Document Type table. Each document code must be assigned a document type. / R / VarChar / 8 / Same as in AMS_DOCUMENT
DOC_CD / Document Code / The alpha-numeric identification code assigned to the document on the Document Control table. Each document code must be unique within the application. The document code is a required field when creating a new document. It also may be selection criteria on a parameter table, a key to a specific business rule on a control table, or the document code recorded on a historical record. / R / VarChar / 8 / Same as in AMS_DOCUMENT
DOC_DEPT_CD / Department Code / The department code assigned to this document. / R / VarChar / 4 / Same as in AMS_DOCUMENT
DOC_UNIT_CD / Unit Code / The unit code associated with this document. / R / VarChar / 4 / Same as in AMS_DOCUMENT
DOC_ID / Document Id / The document code and number that is either manually assigned or automatically generated by the system if you do not enter this information. The version number is assigned automatically. Duplicate document identification numbers are not allowed in the system. / R / VarChar / 20 / Same as in AMS_DOCUMENT
DOC_VERS_NO / Document Version Number / The version number assigned to this document. The version is incremented with each modification draft and after with a cancellation. / R / Number / 10 / Same as in AMS_DOCUMENT
CUST_ACT_STA / Customer Active Status / The active status of the record. Valid values are: Active, Inactive, Suspended, Discontinued, Debarred, Delete, andVSS Rejected. Default is Inactive. / R / Number / 10 / “2” = Active
CUST_APRV_STA / Customer Approval Status / The approval status of the record. Valid values are: Incomplete, Reviewed, and Complete. Default is Incomplete. Reviewed indicates the information has been reviewed, but the record is not yet ready for use in the system for purchases/payments. Complete indicates all information has been reviewed and approved for use. / R / Number / 10 / “3” = Complete

2.1.11VCC Customer XML Example

This example is for aVCC with one billing address, one customer account,and one certification line.