Import Fields to a System

You can upload field metadata for a System in a zipped JSON file using the upload option on the system's asset detail page. This process for adding field metadata to a system will eventually be replaced by a process driven by our REST API. For more information about the capabilities and advantages of Syniti Knowledge Tier's REST API, refer to Export, Create and Replace Assets.

This topic contains the following sections:

Fields JSON import file format

Use the following schema information to format the JSON file that is used to load field metadata for a System.

NOTE: The only required value in the import file is fields.

Format:

{

"fields":[

{

"name": "...",

"location": {...},

"type": {...}

}

]

}

 

Sample JSON file:

{

"fields":[

{

"name":"Country",

"location":{

"technicalName":"COUN",

"path":"dbo.KNA1.COUN"

},

"type":{

"data_type_intent":"text",

"base_data_type":"NVARCHAR",

"range":{

"min_value":null,

"max_value":null,

"range_value":null,

"range_data_type":"lookups.Country"

},

"precision":0,

"length":128,

"encoding":"UTF-8",

"identity":false,

"optional":false

},

"tags":null,

"usage":null

}

]

}

Properties in “root”:

Property

Description

Notes

Example 1

fields

Array of JSON object

This value is required.

NOTE: See properties below

{

"fields":[

{

"name": "...",

"location": {...},

"type": {..}

}

]

}

Properties in “fields” array:

Property

Description

Notes

Example 1

name

The friendly name of the field.

This is the Friendly Name that displays in the UI on for the data set.

Customer Name

location

The full system-specific path, location information for a field.  This is a JSON bag.

 

JSON { … }

(see “location” table below)

type

The full system-specific data type information for a field.  This is a JSON bag.

 

JSON { … }

(see “type” table below)

tags

An array of terms that should be indexed along with this field for search.

[ “KUNNR”, “Customer Name”  ]

usage

Contains system-specific usage or context data, if available.

For example, the content of a database’s data dictionary, a MSSQL column comment, etc.

Default is the empty string.

This field stores customer name data for SAP ERP systems.

Properties in “location”:

Property

Description

Notes

Example 1

technical_name

A short name of the field name

This is the Technical Name that displays in the UI for the data set.

KUNNR

path

The full system-specific path, location information for a field

This is the Location (under the system name) that displays in the UI for the data set.

dbo.KNA1.KUNNR

<custom properties>

Any other custom property that integrators may choose to upload; any other system-specific properties.

 

 

Properties in “type”:

Property

Description

Notes

Example 1

data_type_intent

A simplified data type from this list: text, number, Boolean, date, money, location, binary, identifier

 

text

base_data_type

The field data type

This is displayed in the UI on the Add Fields tab for data sets.

nvarchar

range

Range constraints

Must be present if applicable.

JSON { … } (see “range” table below)

precision

A precision for numeric data types

Must be present when base_data_type is numeric; otherwise, must not be present.

NOTE: This is displayed in the UI on the Add Fields tab on the data set's asset detail page.

 

length

A length value for characters types

Must be present when base_data_type is an array of characters or bytes; otherwise, must not be present.

NOTE: This is displayed in the UI on the Add Fields tab for data sets.

36

encoding

Additional details about the encoding of the field

This can be a string.

“Utf-8”, “latin-1”, IEEE-754 floating point, binary data is in big-endian or little-endian, bools are 0xFFFFF or 0x00001 etc.

identity

Indicates whether this field is an identifier in the underlying model (e.g., a primary key in a relational db context, or a resource  identifier in a REST API context)

Default to false.

true

optional

A determination if the field can be nullable

Default to false.

true

<custom properties>

Any other custom property that integrators may choose to upload; any other system-specific properties.

 

 

Proposed properties in “range”:

Property

Description

Notes

Example 1

min_value

A minimum value for numeric data

Must be present if applicable. Must not be present if not applicable.

-7.25

max_value

A maximum value for numeric data

Must be present if applicable. Must not be present if not applicable.

13

range_values

A finite list of values drawn from the default range of the baseDataType.

May be present if applicable. (If the data set would be really long, it might not be possible to include.)

 

Must not be present if not applicable.

[ “Sunday”, “Monday”, “Tuesday”, “Wednesday”, “Thursday”, “Friday”, “Saturday” ]

range_data_type

The name of the range constraint (e.g. a FK table name)

May be present if applicable.

 

If applicable and rangeValues is not present, then this property must be present.

“DaysOfTheWeek”, “dbo.DaysOfTheWeek”

The upload file must be zipped (compressed). The zipped file can contain multiple JSON files to organize the files.

For example:

SAPFileUpload.zip can contain:

  • SAP (directory - optional)
    • HRFields.json
    • FinanceFields.json
    • LegalFields.json

Or it can contain one file

SAPFileUpload.zip

  • SAP (directory - optional)
    • Fields.json

To upload field metadata for a System:

  1. Add a System.

    OR

    Search for a System and open the asset detail page.

  2. Click the list box for the System.

  3. Select Upload Metadata.
  4. Drag and Drop the JSON file onto the upload modal.

    OR

    Browse for the file.

  5. Click Upload.

IMPORTANT: You will receive a message in the Notifications panel once the file has been processed to indicate success or to inform you of issues with the import.

After you receive a message that the upload succeeded, you can use your browser refresh option to update the count in the Fields panel to verify the upload. Next, the fields can be used to set up Data Sets. Refer to Set Up a Data Set.

Remove fields from a system

You can remove specific fields (or a group of fields) from a System if you re-import to a System with the import file in which fields that had been previously imported to that System are not included. The fields that you choose to exclude from the newly imported file are marked as Removed from System in any Data Set where the fields had been added.

If a field that was removed from a System is subsequently re-included in the import file and imported to the System again it is made “active” again in any data set in which it has been used.

Search uploaded fields

To search for specific fields that have been uploaded to the system:

  1. Click the Fields tab.
  2. Enter a Name or Location for specific fields to filter your search results.
  3. Click the Search icon.