On this page
|
Legacy SHINES reference document. This page captures a Georgia DHS SHINES interface design as written (vendor spec, typically 2007–2025). It documents the system being replaced, not CRAIG behavior. CRAIG’s current implementation of the same data exchange lives under the craig-exchange API reference and in the design documents. Use this page only when mapping legacy integrations during CRAIG rollout. |
Interface Detailed Design Document
TCM * Interface*
Georgia Department of Human Resources
Statewide Automated Child Welfare Information System
(SACWIS)
05/11/2007
Version 1.3a
Table of Contents
General Design (Functional)
| Req. # | Validated Requirement |
|---|---|
555.11 |
Send Provider’s Federal Tax ID number to Financial System |
555.12 |
Send Provider’s SSN to Financial System |
555.13 |
Send Provider’s W-9 Date to Financial System |
555.14 |
Send Provider’s Contract number to Financial System |
555.15 |
Send Date that the Provider’s information was last updated |
555.16 |
Send Provider’s Information nightly |
555.17 |
Send child’s first name |
555.18 |
Send child’s middle name |
555.19 |
Send child’s last name |
555.21 |
Send child’s date of birth |
555.22 |
Send child’s gender |
555.23 |
Send child’s social security number |
555.24 |
Send Child’s SUCCESS ID |
555.25 |
Send Child’s Medicaid Number |
555.26 |
Send Child’s Provider’s Name |
555.27 |
Send Child’s Provider’s ID |
555.28 |
Send Waiver types |
555.29 |
Send Program Code |
555.31 |
Send Daily Per diem rate |
555.32 |
Send Monthly Rate |
The above were the initial requirements collected. Some of them were later invalidated due to changes requested by interface partners and due to constraints in their systems. The following detail design captures the most up-to-date functionality that the interface is designed to perform
Introduction
Document Purpose
The purpose of this document is to give a detailed functional description of how the TCM interface operates.
Functional Overview
Georgia Case Managers make contact with their clients on a regular basis. Certain contacts are considered to be part of Targeted Case Management (TCM). TCM contacts differ from other contacts in that the services provided by the Case Manager are re-imburseable by the Federal Government through the Medicaid program. A number of conditions need to be met for a TCM contact, but the key condition is that the visit is health or medically related.
The Georgia SHINES Contact Detail page will be updated to ask questions to verify that the contact was indeed a valid TCM contact. For a CPS ongoing case, the contact needs to be billed on behalf of the guarantor , which is a child that must be in one of four eligible programs. Currently, those programs are SSI Medicaid, Adoption Assistance Medicaid, Children’s Medical Service Program, or the Georgia Pediatric Program. For a foster care case, the child does not need to be in a special program, and the primary child is typically selected to bill against. The Contact Detail page allows the Case Manager to select which child to bill against; therefore, it is not determined by program logic.
The key advantage of this interface is that is helps to generate revenue for Georgia DFCS.
The SHINES – TCM interface leverages GTA’s webMethods broker technology to pick up requests from the Georgia SHINES database and send them onto to SMI by whatever works best for SMI. Tentatively, that will involve the broker software writing directly to SMI tables created for the SHINES interface. The backup plan is for the webMethods broker to send XML files to SMI. For data coming back, SHINES will provide a web service. Regardless, the precise mechanism that GTA uses to interface from the broker to SMI will be defined in the GTA Integration design for SMI, and it will be decoupled from the SHINES interface and thus transparent to SHINES.
Functional Description
SHINES Case Managers will enter contacts with clients through the Contact Detail page. The user can select TCM as a type, select the primary or guarantor child depending on whether the case is in Foster Care or CPS Ongoing, answer questions about what programs that child is a part of, what medical services were provided and record the contact. As the TCM billing cycle approaches, TCM contacts and related Person information is sent to SMI for Medicaid billing. The interface is critical as it supplies revenue to Georgia DFCS.
If a claim is rejected through the interface, the claim in SHINES is marked as rejected. The TCM page in SHINES allows a Case Manager to search for rejected claims. The Case Manager and/or the Medicaid Billing Unit can correct the data on the Contact Detail page and/or the Person Detail page. Only the Medicaid Billing Unit can then come back to the TCM page to check the checkbox to re-submit the claim on the next cycle.
Table of Input Fields
| Static/ Dynamic | Required (Yes, No) | Data Name | Description | Possible Value | Type | Length |
|---|---|---|---|---|---|---|
Dynamic |
Y |
Transaction ID |
Unqiue transaction ID from SHINES perspective |
Number |
16 |
|
Dynamic |
Y |
Claim ID |
ID of the TCM Claim |
Number |
16 |
|
Dynamic |
Y |
Customer Name |
Name elements for Guarantor or Primary child |
|||
Dynamic |
Y |
Customer DOB |
Date of Birth for child |
|||
Dynamic |
Y |
Medicaid Number |
Medicaid Number for child. 12 digit if we have it, else the 10 character version |
12 digit MHN number or CRS ID plus an alpha |
||
Static |
Y |
Gender |
Gender of the child |
M or F |
||
Static |
Y |
Billing Charge |
Amount to bill for (static value for us) |
Constant |
||
Static |
Y |
Provider ID |
Medicaid ID for Georgia DFCS |
Constant |
||
Dynamic |
Y |
Date of Service |
Date of the TCM contact |
Date |
||
Static |
Y |
Procedure Code |
Code that indicates a TCM DFCS Contact |
Constant |
||
Static |
Y |
Units of Service |
Number of units of service (1 for us) |
Constant 1 |
||
Dynamic |
Y |
TCN Number |
Only used for re-submissions. This is a link to a prior TCM claim. |
String |
17 |
Table of Output Fields
| Static/ Dynamic | Required (Yes, No) | Data Name | Description | Possible Value | Type | Length |
|---|---|---|---|---|---|---|
Static |
Y |
Transaction ID |
ID of SHINES TCM Transaction |
|||
Static |
Y |
Return Status |
Status of create/update transaction |
PAID DENIED PENDING VOID REJECTED |
||
Static |
N |
EOB Values |
Comma delimited string of Rejection Codes if rejected |
String |
30 |
|
Static |
N |
Pay Date |
Date of Payment |
Number |
||
Static |
N |
RA Number |
Remittance Advice Number. Identifies a batch of submitted claims. |
Number |
8 |
|
Static |
N |
TCN Number |
Transaction Number for Submitted TCM Claim from Medicaid to use for re-submissions |
Number |
17 |
Technical Design
Technical Overview
The current plan is that SMI will handle TCM Claims. While the final processing approach could change, it should not affect the interface on the SHINES side.
The SMI application is hosted outside of DHR and GTA and is developed, hosted, and maintained by SMI.
SHINES will write outgoing information into a separate interfacing tables for TCM. The GTA webMethods broker will access those tables directly via JDBC support, convert them into webMethods objects, and then send them to SMI. The current plan is that the broker will either write records into incoming SMI tables or send XML files to SMI. However, the webMethods broker will handle that transformation and transport for us, so technically it is not our concern.
The major technical assertion is that the interface will be asynchronous. The end user of SHINES is not waiting on a response from the SMI system before proceeding to the next step. SHINES will create the outgoing interface records through an offline scheduled process. How often the broker picks up these records is out of the hands of the SHINES team, but should be soon after SHINES generates the outgoing records. The current plan is to run on the 7th and 25th of the month to pick up new claims, and run again on the 15th of the month to pick up resubmissions.
SHINES will need to host a web service for the response to these transactions. There will be one web service for handling client TCM Claim responses. The GTA webMethods broker will be invoking these SHINES web services when it picks up outgoing responses from the SMI system. SMI is currently a batch-oriented architecture on their side. The SHINES side is architected to support that, but more rapid message handling essentially involves a configuration option in the broker, with no code changes need on the SHINES side.
In summary, the outgoing messages will be handled by basic inserts into a new database tables that other applications can subscribe to. The SHINES application code writes out messages to the table; therefore, there is no performance impact to the live SHINES application if there are delays relaying a message out to the SMI application in Carrolton. SHINES will be creating records in real-time. Incoming messages will be processed in real-time via web service invocations that will hook into the SHINES Enterprise Java Bean layer.
Below is an Entity Diagram for the outbound tables used by this interface.
SMI Technical Specifications
Hardware/OS: HP-UX on HP Hardware
Programming Language: C
Database: Informix
Transactional Monitor: N/A
Physical Location: SMI in Carrolton, GA
Current Interfaces: Batch text files
Protocols: Secure FTP
Expected Volume of Transactions: TBD
Technical Description
The Case Manager will record Contacts on the Contacts page in SHINES. TCM contacts are saved in the Contact table as normal, but a TCM Claim record is also written to the TCM_CLAIM table. This table has a person’s name and basic claim status, with links to the actual client (primary child or guarantor as selected by the Case Manager) in the Person table and the record in the Contact table.
At the scheduled time, a process will scan the TCM_CLAIM table for claims that are ready to send. The job will update the client information in the TCM_CLAIM table if needed, and more critically the job will take information from TCM_CLAIM, the PERSON table, the PERSON_ID table, and the CONTACT table and populate the TCM_CLAIM_OUTBOUND table in the SACWISIFC schema. The scheduled process will likely run on the 7th of the month (near the 5th working day) and the 25th of the month to pick up new submissions. The process is expected to run on the 15th of the month to process re-submissions.
The GTA interface broker, webMethods, will scan the TCM_CLAIM_OUTBOUND table with the Oracle JDBC adapter, and generate messages to SMI. The name fields (first name, last name, middle name, suffix) need to have punction removed before passing on to the TCM interface. The GTA broker should remove dashes and other similar characters from these fields.
Message Description
This message contains TCM Claim data, which consists of the client name, medicaid number, Georgia DFCS Provider ID, service date, and related billing information. The provider id may be an issue in that children < 18 years old are billed via one provider number, and people over 18 years old are billed on a different provider number. The provider number used for over 18 year olds is coordinated with the Office of Aging TCM.
TCM Claim Outbound table – SHINES publishing new or updated TCM Claims
| Attribute/Logical Rolename | Domain | Datatype | Null | Definition | Use in Interface |
|---|---|---|---|---|---|
ID_TCM_CLAIM_OUTBOUND |
ID |
NUMERIC(16, 0) |
N |
This is the unqiue identifier for a TCM outbound transaction. It is unique even for re-submissions. |
|
DT_LAST_UPDATE |
DT_LAST_UPDATE |
DATE |
N |
Date of insert or last update |
|
INTERFACE_STATUS |
VARCHAR(3) |
N |
Status of this record with regards to the interface - Waiting (WTG), NEW, INP (In Process), SNT (Sent), ERR (Error). A record will initially start out as Waiting, until the custodial parent (artificial) has been created in CRS. Once that is obtained, the status will progress to NEW, and be ready for be picked up by the broker. |
||
DT_PROCESS |
DATE |
Y |
Date sent by the interface (Sent) or errored out (Error) |
||
CD_ERROR |
VARCHAR(10) |
Y |
If there was an error sending this record, an error code as to why is stored here. |
||
DT_TCM_REQUESTED |
DATE |
Y |
This is the date that this record was originally created by SHINES batch processing. Essentially, it is the date of the batch run. |
||
ID_TCM_CLAIM |
ID |
NUMERIC(16, 0) |
N |
TCM Claim ID |
|
NM_PERSON_LAST |
VARCHAR(22) |
Y |
Last name of the client |
||
NM_PERSON_FIRST |
VARCHAR(12) |
Y |
First name of the client |
||
NM_PERSON_MIDDLE |
VARCHAR(12) |
Y |
Middle name of the client |
||
CD_PERSON_SUFFIX |
VARCHAR(2) |
Y |
Code representing the suffix appended to a name for distinction (e.g. ,Jr., Sr.) of the client |
||
CD_PERSON_SEX |
VARCHAR(1) |
N |
Code representing gender of the client |
||
DT_PERSON_BIRTH |
DATE |
Y |
A date indicating the date of birth of the client |
||
NBR_MEDICAID |
VARCHAR(15) |
Y |
Medicaid Number/MHN Number of the client (primary child for foster care, guarantor if CPS ongoing) |
||
AMT_BILLING_CHARGE |
NUMERIC(6, 2) |
Y |
Amount billed to Medicaid. This is a fixed number. |
||
TXT_PROVIDER_ID |
VARCHAR(15) |
Y |
The is the provider id for DFCS in Georgia. This will be a fixed value. |
||
UNITS_OF_SERVICE |
NUMERIC(2, 0) |
Y |
This is the units of service, which for TCM claims is always 1. |
||
PROCEDURE_CODE |
VARCHAR(8) |
Y |
Medicaid Procedure Code. This is a fixed value for TCM claims from SHINES. |
||
DIAGNOSTIC_CODE |
VARCHAR(5) |
Y |
Diagnostic code. This is a fixed value of V61.9 for TCM claims from SHINES. |
||
NBR_TCN |
VARCHAR(17) |
Y |
Initially, this is a value that we get back from the interface. For re-submitting a claim, this value will be supplied. |
||
DT_SERVICE |
DATE |
Y |
Service Date – date of actual contact with client |
Table of Fields Coming Back from Target System (SMI) in Web Service
| Static/ Dynamic | Required (Yes, No) | Data Name | Data Type | Length | Transformation Rules | Validation Rules | Default |
|---|---|---|---|---|---|---|---|
Static |
Y |
Transaction ID |
Number |
16 |
Unqiue ID for this particular transaction within SHINES |
||
Static |
Y |
Return Status |
String |
2 |
1 – PAID 4 – DENIED 5 – PENDING 22 - VOIDED 99 – REJECTED by SMI |
||
Static |
N |
EOB Codes |
String |
30 |
Comma delimited reason codes for why rejected |
||
Static |
N |
Pay Date |
Date |
||||
Static |
N |
TCN Number |
String |
17 |
|||
Static |
N |
RA Number |
String |
8 |
Method Narratives
The code for the Contact Detail page will be updated to record TCM contact data in both the CONTACT table and the TCM_CLAIM table with a status of “not submitted” (NS). For the benefit of the TCM Claim search page and its performance, the client name and medicaid number are replicated here.
When the COBOL batch job runs at its scheduled time through the COBOL batch interface, it will scan the TCM_CLAIM table for records in a “not submitted” status. It will update the status to “submitted” and update the client name and/or Medicaid number if that information in the Person table has changed. The job then selects fields from the CONTACT and PERSON tables and creates a row in the TCM_CLAIM_OUTBOUND table with a status of “New”.
The webMethods broker will poll this table with the JDBC adapter for Oracle looking for records that need to be sent or resent, based on INTERFACE_STATUS field. When the broker has picked up the message, it changes the INTERFACE_STATUS to picked up, and updates the DT_PROCESS field. When the message has been delivered to SMI, the INTERFACE_STATUS field is updated to reflect it was sent, and the DT_PROCESS field is updated to reflect the date/time of delivery.
The web service that handles the TCM claim results will update the status field in TCM_CLAIM. If the claim was successful, the web service will update the PAY_DATE field as well. If it was denied, the web service will update the CD_DENIAL field with EOB error codes. If multiple codes are received, they will be stored comma-separated.
For a re-submit, the TCM Claim search page is used to find denied/rejected entries. Once data is corrected on the Contact or Person page, the Medicaid Billing Unit user can select a checkbox to re-submit the TCM Claim, creating a new TCM_CLAIM record with the TCN number returned from the DENIED claim record and a status of “not submitted”.
If a TCM_CLAIM is rejected by SMI (as opposed to DENIED by Medicaid), the re-submission process will update the exisiting TCM_CLAIM recrd and set the status to “not submitted”.
The TCM_CLAIM.DT_STATUS will be update to the SYSDATE when the TCM_CLAIM table is updated.
Error Handling
Error codes are written by the webMethods broker into the CD_ERROR field. The broker is responsible for retries, and if needed, emails are sent by the broker to administrators to notify them of problems in this interface.
Field Level Errors
If a field in a record to be extracted has a validation error, that row will be skipped, CD_ERROR and DT_PROCESS updated, and an email should be sent to the application administrators by the broker.
Row Level Errors
The broker should update CD_ERROR and DT_PROCESS if possible. Regardless, the broker should send an email to application administrators.
Process Level Errors
The most likely process level errors will be network and other communications errors. The interface broker will handle retries, and send emails to application administrators as needed.
If the claim itself is rejected, the user will review rejected claims in the SHINES application, correct the information, and then mark the claim for resubmission.
Triggering/Scheduling
Broker will be configured to scan the TCM_CLAIM_OUTBOUND table. A batch job will be launched by the COBOL batch scheduling system to pull TCM Claims out of the TCM_CLAIM and related tables and populating the TCM_CLAIM_OUTBOUND table. The trigger will be the configuration of the batch scheduler for this job.
Matching Criteria
Matching of responses to our requests will be done through the Transaction ID the specific record in TCM_CLAIM_OUTBOUND. Re-submissions use the NBR_TCN field as well. The inbound web service will use the ID_TCM_CLAIM field in TCM_CLAIM_OUTBOUND to determine which TCM_CLAIM record to update with statuses.
Dependencies
The Resource Detail page must have all mandatory fields filled out and a contract approved before it can be transmitted to SMILE. Adoptive/Foster homes must be added and *approved *before being extracted and transmitted to SMILE.
TCM_CLAIM table
| Attribute/Logical Rolename | Domain | Datatype | Definition |
|---|---|---|---|
ID_TCM_CLAIM |
ID |
NUMERIC(16, 0) |
TCM Claim ID |
DT_LAST_UPDATE |
DT_LAST_UPDATE |
DATE |
Date of insert or last update |
ID_PERSON |
NUMERIC(16, 0) |
Staff ID |
|
ID_STAGE |
NUMERIC(16, 0) |
Stage ID |
|
ID_PERSON |
NUMERIC(16, 0) |
Person ID |
|
NM_CLIENT |
VARCHAR(30) |
Client Name |
|
NBR_MEDICAID |
VARCHAR(15) |
Medicaid Number |
|
CD_STATUS |
VARCHAR(3) |
Status |
|
CD_DENIAL |
VARCHAR(30) |
Denial Reasons (EOB codes that are comma delimited) |
|
ID_CONTACT |
ID |
NUMERIC(16, 0) |
Identifier of Contact record that contains most of the details. |
DT_STATUS |
DATE |
Status Date |
|
DT_SERVICE |
DATE |
Service Date |
|
NBR_TCN |
VARCHAR(15) |
TCN Number for this particular Medicaid transaction |
|
DT_PAY |
DATE |
Pay date for the claim |
Document Change Log
| Date | Author | Change Description |
|---|---|---|
10/09/2007 |
Michael Chillman |
Added code of rejected status |
09/14/2007 |
Michael Chillman |
Updated requirements |
09/06/2008 |
Michael Chillman |
Added entry for TCM.DT_STATUS update |
05/11/2007 |
John Ramspott |
Added a few updates to functional input/output tables. |
03/29/2007 |
John Ramspott |
Updated diagnostic code to V61.9 |
03/02/2007 |
John Ramspott |
Updated based on State Feedback |
02/23/2007 |
John Ramspott |
Initial Document Creation |
Note: A new row explaining document changes must be added to the Document Change Log for each revision. The Document Change Log must be maintained in reverse chronological order. The most recent changes are on the top of the list.