GSAPI Data Importing: Interface Import

Interface Import allows you to send any structured data to Good Sign through an interface using a single endpoint.

This is used for master data, product data, organization data, object data, or any customer‑specific dataset handled by an interface.

Good Sign introduced the unified import endpoint in 2023_1, and expanded it in 2025_2 to support automatic staging table initialization and dynamic column additions.

Interface Import is one of the most flexible GSAPI capabilities because it adapts to your interface structure.

2. When to Use Interface Import

Use this method when you need to:

• import structured rows (JSON) into an existing interface
• send multiple data fields per row
• extend your data model over time without UI configuration
• automate recurring integrations (e.g., nightly syncs from ERP/CRM)
• send sub‑arrays or nested JSON data

Typical use cases:

• product catalog updates
• organization hierarchy sync
• device/object imports
• metadata updates
• custom integration tables for advanced billing logic

3. Required User Rights

To use the Interface Import endpoint, your user needs:

4. Endpoint

POST https://api.goodsign.cloud/api/interface/gsapi/<interfaceName>/import

Example:

POST https://api.goodsign.cloud/api/interface/gsapi/carsimporter/import

Optional parameters:

5. Sending Data

Below is an example import for an interface named carsimporter.

Figure 1: JSON import example in a REST client

Minimal JSON example

[
  {
    "brand": "Volvo",
    "model": "XC60",
    "productionyear": 2023
  },
  {
    "brand": "Tesla",
    "model": "Model Y",
    "productionyear": 2024
  }
]

URL with notify=1

Processes data immediately after import:

POST .../carsimporter/import?notify=1

Response example

{
  "ret": 1,
  "received": 2,
  "datagroupid,": 94512
}

• datagroupid identifies the batch in the staging table for debugging.

6. Checking Available Columns (Resolve Columns)

Use a GET request to see the fields your interface currently supports:

GET https://api.goodsign.cloud/api/interface/gsapi/<interfaceName>/import

Good Sign returns a list of:

• available fields
• field types
• whether a field is part of the Key Fields (deviceKeyFields)

Figure 2: Resolve columns GET request result

This helps confirm which columns your JSON must contain.

Example response:

[
  {
    "field": "brand",
    "type": "string",
    "keyvalue": 0
  },
  {
    "field": "objectkey",
    "type": "string",
    "keyvalue": 1
  }
]
``

7. Initializing the Staging Table (init=1)

If the interface has not been used before, the staging table may not exist yet.

Figure 3: UI view of a newly created interface before initialization

To create it:

POST .../carsimporter/import?init=1

If no table exists, the system responds with a message pointing this out.
Resending with init=1 instructs Good Sign to:

1. create the staging table
2. apply current field structure
3. prepare the interface to receive data

Figure 4: Interface staging table after initialization

8. Adding New Columns

If you introduce a new field to your interface, Good Sign can automatically extend the staging table.

Steps:

1. Add the new field to the first element of your JSON array
2. Use init=1 when sending the data
3. Good Sign updates the staging table to include the new column

Example with a new field condition:

[
  {
    "brand": "Volvo",
    "condition": "New"
  }
] 

POST .../carsimporter/import?init=1

After this, the column appears in the Interface UI.

9. Processing Behavior

Interface Import follows the same two-phase flow as other GSAPI imports:

Stage → Process → Result

• Stage: data is written to the interface table
• Process: data is executed by the interface action
• Result: objects or updates created in Good Sign

notify parameter details

For large integrations, notify=1 should only be used for the last batch.

11. Summary

12. Consultant Notes (Advanced)

Staging Table Behavior

The staging table name matches the interface name (e.g., carsimporter).
Changes to staging structure propagate into processing metadata.

Sub‑Arrays

Sub-array data is supported and can be accessed using SQL functions such as JSON_VALUE and OPEN_JSON.

Column Order

When adding new fields, columns in the first JSON object are used to extend the table.
If missing, table updates will not occur.

Error Codes

Negative ret values indicate failures such as:

• missing interface
• malformed JSON
• staging table initialization failure
• field type mismatches

Workload Considerations

For high-frequency imports:

• avoid processing every batch
• monitor processing queue in Datatables
• use Interface Logs for debugging