How to Use the Data Connector to Integrate with Third-Party REST APIs

Products

• IT Management Suite

Issue/Introduction

ITMS administrators often need to synchronize data between the Symantec Management Platform (SMP) and third-party products. Historically, this required a manual, two-step "middle-man" process: exporting data to an intermediate file (like CSV) and then importing that file into the destination system. Administrators now require a way to perform direct data extraction ("pull") and insertion ("push") between ITMS and third-party REST APIs without intermediate files.

Environment

 IT Management Suite (ITMS) 8.8.1 and later

Components: Data Connector, Altiris Software Development Kit (ASDK)

Cause

The primary integration challenge is that JSON formats are not standardized across products. Since these formats cannot be known at "build time," the conversion logic must be defined by the administrator using XML schemas that tell the Data Connector how to interpret the specific REST peer's data structure.

Resolution

With our ITMS 8.8.1 Release (See ITMS 8.8.1 Release Notes), Data Connector now supports direct REST API communication, allowing for seamless data exchange between ITMS and external platforms. Because every third-party vendor uses different JSON structures, ITMS utilizes a flexible XML-based mapping system. This system converts external JSON data into internal ITMS data tables (and vice-versa) in real-time.

The solution involves three new core components within the Data Connector: REST Schema Providers, REST Data Sources, and REST Data Destinations.

1. Create a REST Schema Provider

The Schema Provider acts as the "logic engine" for data transformation.

1. In the Symantec Management Console, navigate to Settings > Connector > Schema Providers.
2. Right-click the folder and select New > REST Schema Provider.
   
   
   
3. In the Schema XML view, define your mapping. Key sections include:
   • <baseUrl>: The endpoint of the third-party API.
   • <columns>: The internal Data Table structure to be built.
   • <request>: Defines parameters (query or body) for the API call.
   • <transform>: The logic used to "walk" the JSON and map values to columns.
     
     
     

2. Configure a REST Data Source (Pull) or Destination (Push)

Once the schema is defined, you must create a Data Source or Destination to execute the call.

1. Navigate to Settings > Connector > Data Sources (or Data Destinations).
2. Right-click and select New > REST Data Source (or REST Data Destination).
   
   
   
3. Select your created Schema Provider from the dropdown.
   
   
   
   
4. OPTIONAL: You can override the Base URL locally within this item without changing the global schema.
   
   
   

3. Diagnostic Testing

Before running live rules, use the built-in Test button to validate your XML mapping.

1. Click the Test button at the bottom of the Data Source/Destination page.
   
   
   
2. Use the View test response as dropdown to verify the results:
• Table: Shows how the data appears in the in-memory Data Table generated from the API response. This represents the dataset that will be passed to the Rule for processing. It does not represent how the data will be stored in the ITMS database.
• Raw: Shows the direct, unformatted response (typically JSON) received from the REST API peer.
• Formatted: Shows a user-friendly JSON tree view for easier readability and navigation.
  
  Note: What ultimately gets written to the ITMS database depends entirely on how the configured Rule processes the data.
  
  
  
  Note: Our example in a “formatted” mode will show json like this:
  
  
  

4. Create an Import/Export Rule

Finally, use the Data Source in a standard rule to automate the data sync.

1. Navigate to Settings > Connector > Import/Export Rules.
2. Create a new rule and select your REST Data Source.
3. Map the source columns to the desired ITMS Data Classes as you would with a CSV or SQL source.
   
   
   

---

Technical Reference Addendum 

For administrators requiring complex mappings, the following logic nodes are supported:

Node	Purpose
<enum> / <iterate>	Loops through JSON arrays to create multiple rows.
<if> / <switch>	Applies conditional logic (e.g., if a field is null or empty).
eval attribute	Applies transformations like math, date formatting, or GUID resolution.
culture / cu	Overrides locale settings for parsing dates/numbers (e.g., en-US vs de-DE).

---

Supplemental Technical Reference & Examples Cookbook

This section provides a deep dive into the XML syntax and advanced transformation logic for the REST Schema Provider. Use these examples as a "cookbook" for handling complex JSON structures and data evaluations.

NOTE: See attached "REST Schema and Evaluations_v2.zip" and "REST Schema – JSON to Data Table Examples_v2.pdf" for more detailed examples and usage.

1. XML Attribute Reference

The following attributes control how the Data Connector UI and the REST API interact:

Attribute	Description
mode	Determines if the parameter is sent as a URL query or in the POST body.
fixed	If set to true, the value is locked in the UI and uses the default.
type	Defines the UI control (e.g., list, bool, advanced).
test	Specifies the value used when clicking the Test button in the UI.
cu / culture	Overrides the local machine's locale for parsing dates and numbers.

2. Transformation Logic Examples (Pull)

These examples demonstrate how to "walk" various JSON structures to populate an ITMS Data Table.

Example A: Simple Array to Table

To convert a standard list of objects into rows:

 

<transform mediaType="application/json">

  <enum path="results" type="array">

    <column name="AssetID" src="property1" />

    <column name="Description" src="property2" />

    <newRow/>

  </enum>

</transform>

Note: <newRow/> (or <row/>) completes the current row and clears values for the next entry.

Example B: Nested JSON into Multiple Rows

When an object contains a nested array (e.g., one computer with multiple software items), use <addRow/> to preserve the outer object's values across multiple rows:

 

<enum path="results" type="array">

  <column name="ComputerName" src="property1" />

  <enum path="software_list">

    <column name="SoftwareName" src="app_name" />

    <addRow/> </enum>

</enum>

Example C: Conditional Logic for Null/Empty Data

If a REST API returns no data for certain fields, use <if> or <switch> to prevent import errors:

 

<switch src="values">

  <case when="null">

    <column name="Status" value="No Data Found" />

    <newRow/>

  </case>

  <default>

    <enum path="values">

      <column name="Status" src="property2" />

      <newRow/>

    </enum>

  </default>

</switch>

3. Advanced Evaluation (eval) Cookbook

The eval attribute allows you to manipulate data during the transformation process.

Goal	Evaluation String	Description
Math	eval=":i32:add(~5)"	Converts value to integer and adds 5.
Date Math	eval=":date:add(~[1.00:00:00])"	Adds exactly 1 day to the timestamp.
ITMS Lookup	eval=":guid:item.Name"	Takes a GUID from JSON and returns the actual Item Name from the ITMS database.
Formatting	eval=":item.ToString():lower"	Resolves an item and forces the output to lowercase.
Rounding	eval=":datetime:truncate(~sec)"	Removes milliseconds from a date-time value.
RegEx	regex=".*-([^\\]+)" result="$1"	Extracts a specific substring using regular expressions.

4. Push Logic (Table to JSON)

When sending data out to a third-party API, you must wrap the Data Table into JSON objects.

Example: Grouping Rows by Resource

To send a single JSON object for a computer that contains an array of its logged-in users:

 

<group by="ResourceGuid">

  <object>

    <property name="resourceId" column="$key" /> <array name="user_logins">

      <enumRows>

        <object>

          <property name="User" column="UserId" />

          <property name="LoginTime" column="AuditDate" />

        </object>

      </enumRows>

    </array>

  </object>

</group>

Verification Checklist

• Test UI: Always use the Test button and switch to Formatted view to see the JSON hierarchy.
• Culture: If dates are failing to parse on a non-English server, add culture="en-US" to the <transform> node.
• Base URL: Ensure the baseUrl uses the correct protocol (HTTPS) for the third-party peer.