logo Staging - Definitions and Best Practices

About this Page

The following definitions are meant to serve as a reference for concepts and terminology you will want to be familiar with during Staging. Please note that this is a living document and additional topics may be added here over the course of the Staging Process. As always, please let us know if there are additional concepts you want to see covered here. All questions concerning Staging should be submitted to data-staging@tylertech.onmicrosoft.com.

Glossary of Commonly Used Terms and Definitions

Guidance and Best Practices for Data Submissions

1. Important IDs to Track

In the Staging Process, Datasets are not separated out by Vendor, and because Staging involves Live Data, the data’s validity is more important. Previously submitted records will sometimes need to be Edited or Deleted, as we will discuss in more depth below. The Staging Pipeline uses three pieces of information to uniquely identify a record: 1) the Record ID, 2) the County, and 3) the Vendor. You will need to track two of these: the Record ID and County. You will need both of these in order to edit or delete records later on. We also highly recommend that you retain the Envelope ID for each submission, as described below.

Please see the following subsections for more information about what this means for you.

The Record ID

Every EntityType (i.e. every dataset) has a Record ID column, denoted as recordid. As described above, this is an identifier for a record. It needs to be unique per County and per Vendor. Please retain the Record ID after each submission.

The County Elements

There are multiple Data Elements that refer to counties: circuitcourtncicnumber, county, sentencingcountyname, and prosecutingcountyname. Please retain the appropriate program-area county element after each submission.

The Envelope ID

PLEASE NOTE: The Envelope ID is not actually stored inside of a record itself. Rather, it is returned in response to a record. (Therefore, there is still a one-to-one correspondence between Envelopes and Records.)

The Vendor

PLEASE NOTE: This is actually tracked behind the scenes; you do not need to track a Vendor ID in your own data. It will be appended to your data on the backend as the Pipeline associates client credential pairs with vendors.

The Timestamp

Please make sure to retain the date and time of each submission you make to the pipeline.

Once more, we highly advise you please retain Envelope IDs for at least a short period of time after every submission, edit, and deletion, because they will help you and us in pinpointing and troubleshooting issues.

2. Triggers for Sending Records

There are certain events upon which a record should be submitted, either in the form of a new record or an update to an existing record. Both will use the di-aoic-new-record-event. However, the specific events that should trigger these submissions vary depending on the Data Element that is modified. Please consult the following spreadsheets for more information: Data Elements Please see the “Dataset Overview” tab in each Dataset spreadsheet. When a new record is added, or the Key Date field within a given Dataset is modified, that serves as a trigger.

Example: In the Disposition and Release dataset for Pretrial, suppose there is an existing record. If that record’s Supervision End Date is changed, that should trigger a new event, because Supervision End Date is the Key Date for that dataset.

3. Pipeline Critical Elements vs. Required Fields

The Pipeline Critical Elements are necessary in order for data to be accepted by the pipeline. Please see the Pipeline Critical Elements section below for more information.

Required Fields are elements that are necessary from a business perspective, but are not mandatory for data to be transmitted successfully. You can see which fields are Required in the Data Elements spreadsheets: Data Elements

4. Data Elements that Can Have Multiple Values

The following list is an example of data elements that can have multiple values:

Reason Detained

Reason Inactive

Sentence Type 1

Arrest Card Document

Control Number

Conditional Assessment Type

Continuance/postponement Reason

Defendant Alias Name

Document Control Number

Conditional Assessment / Conditional Assessment Amount

Civil Case Closure Reason

Modification Type

Accommodation Granted

Continuance/postponement reason

Conditional assessment type

Modification type

Defendant Alias Name

5. Partial Caseloads

Partial Caseloads will be allowed in Staging. We are mentioning it now because later, in Production, we will be establishing criteria for which Caseloads should be included, and Caseloads prior to this criteria being established will need to be excluded.

6. Spaces and Capitalization

In the Staging Domain, the Data Elements that are categorical in nature have rigorous validation against finite, predefined sets of enumerated values. These are listed in the Data Elements for the applicable variables.

For these elements, please ensure that the values you provide for these elements match one of the enumerated values precisely, with no differences in spacing and the same casing of letters.

7. Accidentally Sent Incorrect Data. Now what?

Accidents happen, and we want to help you resolve them. Even though this is a Staging Environment and not Production, we ask for your cooperation during this process in correcting erroneous records so as to reflect the practice of data validity that will be required in Production.

We have two mechanisms for correcting data that you can leverage depending on the nature of the correction needed: Edits and Deletions.

Guidance and Best Practices for Data Modification (Edits and Deletions)

1. Correcting/Augmenting Records (Edits)

If you simply need to correct the values of an existing record, or add to their values, you can do so using the same di-aoic-new-record-event EventType that you use for new records. The difference here is that you only need to specify the Record ID and County of the record whose values you want to correct (or add to); you do not need to specify the Pipeline Critical Elements again. The fields you specify in EntityData - and only those fields - will have their values updated. Other fields, and their values (if applicable), will not be affected.

Here’s an example. (This is a continuation of the example here. What does this sample update do? Remember that only the fields specified are modified. The others are left alone. So we specify the recordid and sentencingcountyname, which are mandatory, even though we aren’t changing them. The system finds that there is an existing record with that Record ID-County combination, from the earlier example.

In Summary: The only field that changes after the following submission is the individual’s dateofbirth, which had been 1993-12-23 and will now be 1991-01-01. This illustrates how to edit the value of a specific column in a record (i.e. a “cell” in spreadsheet terms).

{
    "ResolveMappings": true,
    "ValidateEnvelope": true,
    "Events": [
        {
            "EventType": "di-aoic-new-record-event",
            "Entities": [
                {
                    "EntityType": "di-aoic-problemsolvingcourts-screening",
                    "LinkEntity": true,
                    "EntityData": {
                        "recordid": "1234",
                        "sentencingcountyname": "Sangamon",
                        "dateofbirth": "1991-01-01"
                    }
                }
            ]
        }
    ]
}

2. Removing Records Entirely (Deletions)

In other situations, an entire record may be erroneous. If that’s the case, you can leverage the new di-aoic-delete-record-event EventType for deletion in order to remove an entire record. You specify the record which you want to delete by using the combination of the recordid and sentencingcountyname to refer to it.

Here’s an example. Note that we use the di-aoic-delete-record-event and refer to the record using its Record ID and County.

{
    "ResolveMappings": true,
    "ValidateEnvelope": true,
    "Events": [
        {
            "EventType": "di-aoic-delete-record-event",
            "Entities": [
                {
                    "EntityType": "di-aoic-problemsolvingcourts-screening",
                    "LinkEntity": true,
                    "EntityData": {
                        "recordid": "1234",
                        "sentencingcountyname": "Sangamon"
                    }
                }
            ]
        }
    ]
}

3. Delete an Entire Case, not just a Record

There may be a time an entire case needs to be deleted. If you need to delete an entire case, use the EventType di-aoic-delete-record-event and include recordid and sentencingcountyname. Please only delete one record per API call; if you need to delete multiple records, please perform each deletion in its own separate API call.

4. Nullify a Field within a Record without Deleting the Entire Record

To nullify a field in an existing record, you will use the di-aoic-new-record-event EventType and include the appropriate recordid and sentencingcountyname of the record. Then specify the field in EntityData whose values you want to nullify. To nullify a text or value field, send a blank string (“”) or, in the case of a number field, send -1. The fields you specify in EntityData - and only those fields - will have their values updated. Other fields, and their values (if applicable), will not be affected.

In the example below, DCN (of type string) and AOICCode (of type number) are both being nullified.

{
    "ResolveMappings": true,
    "ValidateEnvelope": true,
    "Events": [
        {
            "EventType": "di-aoic-new-record-event",
            "Entities": [
                {
                    "EntityType": "di-aoic-problemsolvingcourts-screening",
                    "LinkEntity": true,
                    "EntityData": {
                        "recordid": "1234",
                        "sentencingcountyname": "Sangamon",
                        "dcn": "",
                        "aoiccode": -1
                    }
                }
            ]
        }
    ]
}

5. Modifying Data in a Field that Allows Multiple Values (Add or Delete)

Whether you want to add value(s) or remove value(s) from a fields that allows multiple values, the steps are the same. You will need to use the di-aoic-new-record-event EventType and include the appropriate recordid and sentencingcountyname of the record. Then specify the field in EntityData whose values you want modify (add or delete) and include all values needed for the field. All of the previous data for that field will be reset and will now match the most recent value(s) submitted. For example: if DCN L00000001 was already entered into the DCN field and an additional needs to be added, submit DCN L00000001;L00000002 to append the field.

{
    "ResolveMappings": true,
    "ValidateEnvelope": true,
    "Events": [
        {
            "EventType": "di-aoic-new-record-event",
            "Entities": [
                {
                    "EntityType": "di-aoic-problemsolvingcourts-screening",
                    "LinkEntity": true,
                    "EntityData": {
                        "recordid": "1234",
                        "sentencingcountyname": "Sangamon",
                        "dcn": "DCN L00000001;L00000002"
                    }
                }
            ]
        }
    ]
}



Guidance and Best Practices for API Documentation

1. Security Token

You must use your Client ID and Client Secret to request a Bearer Token. Remember that Bearer Tokens expire after 1 hour.

Endpoint URL: https://tyler-alliance-system-demo.auth-fips.us-gov-west-1.amazoncognito.com/oauth2/token

Action:POST

Header: Please substitute thisIsMyClientId and thisIsMyClientSecret with your Client ID and Client Secret, respectively.

{
  "Content-Type": "application/x-www-form-urlencoded",
  "Authorization": "Basic thisIsMyClientId:thisIsMyClientSecret"
}

Body: grant_type=client_credentials

2. Record Submission and Deletion

Please note that a PUT call is used for both submissions and deletions. You distinguish between the two with the EventType, which can be either di-aoic-new-record-event or di-aoic-delete-record-event.

Endpoint URL: https://api.test-alliance.tylerhost.net/exchange/Messages

Action: PUT

Header: Please substitute thisIsMyAuthToken with the Security Token you received in the step above.

{
  "Content-Type": "application/json",
  "Authorization": "Bearer thisIsMyAuthToken"
}

Body: This will be the JSON contents containing your data submission. See here for an example: Staging instructions

Guidance and Best Practices for Pipeline Critical Elements

The following section provides a series of data element examples for each program. Again, unlike the Required Fields denoted in the Data Elements, the Pipeline Critical Elements here must actually be included for a submission to be accepted by the pipeline.

1. Pretrial Program Pipeline Critical Elements

The following elements must be included in every Pretrial record:

Example

{
    "ResolveMappings": true,
    "ValidateEnvelope": true,
    "Events": [
        {
            "EventType": "di-aoic-new-record-event",
            "Entities": [
                {
                    "EntityType": "di-aoic-pretrial-violations",
                    "LinkEntity": true,
                    "EntityData": {
                        "name": "Vendor Name",
                        "prosecutingcountyname": "Cook",
                        "recordid": "3456"
                    }
                }
            ]
        }
    ]
}

2. Probation Program Pipeline Critical Elements

The following elements must be included in every Probation record:

Example

{
    "ResolveMappings": true,
    "ValidateEnvelope": true,
    "Events": [
        {
            "EventType": "di-aoic-new-record-event",
            "Entities": [
                {
                    "EntityType": "di-aoic-probation-individual-background",
                    "LinkEntity": true,
                    "EntityData": {
                        "name": "Vendor Name",
                        "sentencingcountyname": "Kankakee",
                        "recordid": "6789"
                    }
                }
            ]
        }
    ]
}

3. Courts Program Pipeline Critical Elements

The following elements must be included in every Courts record:

Example

{
    "ResolveMappings": true,
    "ValidateEnvelope": true,
    "Events": [
        {
            "EventType": "di-aoic-new-record-event",
            "Entities": [
                {
                    "EntityType": "di-aoic-court-case-status",
                    "LinkEntity": true,
                    "EntityData": {
                        "vendorname": "Vendor Name",
                        "circuitcourtncicnumber": "IL081025J-Rock Island 14th",
                        "recordid": "2468"
                    }
                }
            ]
        }
    ]
}