Example 3 - Optional API Parameters

Introduction and data structure

The Sales Layer API is marked by required parameters as well as optional parameters.

In this third example about the export of items using the SDK, we will do an export with some of these optional parameters allowed by the API. These parameters influence the export of data from the API to the type of value passed in the parameter.

The parameters used in this example are:

group_category_id: this parameter involves products with several categories and defines if exporting them as a single product or exporting the same product for each category. In other words, if the parameter is set as false and the product has two categories, the product will be exported twice.
first_parent_level: it defines whether the parent associated with a modified product is exported. In case of a category modification, the first higher categories will be exported. In the case of a product modification, the associated categories will be exported and, finally, in case of a variant modification, the variant parent will be exported.
same_parent_variants: this parameter defines whether the formats that share the same parent are exported in case one of those formats has been modified.

More information in Other Modeling Parameters | Sales Layer Help Center.

We are going to use the connector created in Example 1, with the same table configuration (see table configuration in Example 1) and the same filters and parameters:

Once again, the only parameter to consider will be the visible status, as we haven’t added any search or label filters in the connector.

We have 14 visible categories:

This time we select 3 products, taking into account that one of them has variants (product with reference 42PH420305221) and another is multi-category (product with reference AAPA780310002):

Among the variants, we select the ones of the product that we have previously chosen:

For the parameter functioning test, we will use the product AAPA780310002 to test the group_category_id parameter, the product 42PM506120061 to test first_parent_level, and the variants of the product 42PH420305221 for the same_parent_variants.

Code

To export the data with the parameters we have mentioned above, we can use the following code as an example:

<?php 
define('LOC_BASE', dirname(__FILE__) . '/');
require(LOC_BASE.'SalesLayer-Conn.php');
require(LOC_BASE.'lib/nice_r-master/Nicer.php');
?>

<!DOCTYPE html>
<html dir="ltr" lang="en-US">
<head>
    <link rel="stylesheet" type="text/css" href="lib/nice_r-master/nice_r.css?version=<?php echo filemtime(LOC_BASE.'lib/nice_r-master/nice_r.css'); ?>"/>
    <script type="text/javascript" src="lib/nice_r-master/nice_r.js?version=<?php echo filemtime(LOC_BASE.'lib/nice_r-master/nice_r.js'); ?>"></script>
</head>

<body>
    <?php

    //SL connector credencials
    $connector_id = 'CN12347H3308C4486';
    $secret_key = '7aeb575d9bf15bfa238e8f01842417a2';

    $last_update= "1597958324";

    //Create object with the credentials on the connector in SL
    $SLConn = new SalesLayer_Conn ($connector_id, $secret_key);

    $SLConn->set_group_multicategory(true);
    $SLConn->set_first_level_parent_modifications(true);
    $SLConn->set_same_parent_variants_modifications(true);

    $SLConn->get_info($last_update);

    if ($SLConn->has_response_error()) {
        echo "<h4>Error:</h4>\n\n Code: ".$SLConn->get_response_error().
             "<br>\nMessage: ".           $SLConn->get_response_error_message();
    } else {
        echo "<h4>Response OK</h4>\n".
             "<p>".
             "API version: <b>".            $SLConn->get_response_api_version()          ."</b><br />\n".
             "Time: <b>".                   $SLConn->get_response_time('unix')                 ."</b><br/>\n".
             "Default language: <b>".       $SLConn->get_response_default_language()     ."</b><br/><br />\n".
             "</p>";

        //Print API response
        $n = new Nicer($SLConn->get_response_table_data());
        $n->render();
        echo "<hr/>";
    }       
    ?>
</body>
</html>

We start by creating a SalesLayer_Conn() class with the connector's credentials as parameters. These credentials can be found in the Sales Layer connector and have been saved in the $connector_id and $secret_key parameters (see Example 1).

We can now start defining the parameters:

group_category_id: With the call to the SDK function set_group_multicategory ().
first_parent_level: with the SDK function call set_first_level_parent_modifications().
same_parent_variants: with the SDK function call set_same_parent_variants_modifications().

These three functions accept a Boolean value as a parameter. In addition to that, the data exported by the API will change, depending on whether it is true or false.

We can see their differences in the analysis of the results.

For the call to the get_info () function of the class, we select a last_update date which is subsequent to the last modification date, so that we can make changes in Sales Layer and observe the results. Every time we change something, we have to change the last_update date in the code to export the modified item/s.

Note: The date is usually saved during the syncs so that it can be always used on the next call.

After verifying that the API has not returned any error through the has_response_error () function, we can print the relevant information with the SDK functions:

The API version through the get_response_api_version() function
UNIX date of the exact time of the API call with the get_response_time() function
The default language of the PIM by calling the get_response_default_language()function

Thanks to theNice_r library (click here for more info) we can now print the data returned by the API with the get_response_table_data() function.

Execution and its results

In order to run the script, we have to take into account the parameters passed to the API.

In the previous code example, we used the following parameters:

group_category_id: true
first_parent_level: true
same_parent_variants: true

They can be set as true or false as we are going to see below.

We will start by studying the API response on the group_category_id parameter. This parameter exports a multi-category product as many times as the number of its categories.

We are going to return to the multi-category product with the reference AAPA780310002:

We see that their categories have ACCE01 and VERA02 as references:

With the parameter set as true, the product will be exported as a single product with two categories in the section_reference field:

If we set the parameter as false, the product will be exported twice but with different values in the section_reference field (the field where the category reference is found):

By changing the parameter to true, the API exports the item only once with the two categories in the section_reference field. Setting the parameter as false, the API will export the item twice, but changing the section_reference field

Let’s take a closer look at the API response to the first_parent_level parameter. This parameter defines if exporting an item which is superior to a modified item.

We now make a change to the reference product 42PM506120061.

With the parameter set as true, both the category tree and the product are exported:

With the parameter set as false, only the product is exported:

As we can see, the API exported the first item in the hierarchy.

If we make a change in the variants table, with the parameter set as true, we get the same result: the items immediately above will export so, in this case, the parent product.

Let's see an example of changing the variant F234946 with the parent reference of 42PH420305221:

As we can see, with the parameter set as true, the parent and the variant are exported:

With the parameter in false, only the variant is exported:

Finally, we will test the API export using the same_parent_variants parameter. When this parameter is set as true, it exports all variants of the same parent, if one of its variants is modified.

Remember that we have the following variants in visible status and that they belong to the same parent reference:

With the parameter set as true and changing one of the variants, the three references will be exported like this:

With the parameter set as false and changing one of the variants, only the modified one will be exported:

As a summary, the following table shows how the API works, depending on the type of parameter:

group_category_id - with the call to the SDK functionset_group_multicategory()

Parameter	true	false
Result	The product will be exported only once with the categories grouped in the same field.	The product will be exported based on its number of categories, containing only one category in the category reference field.

first_parent_level - with the call to the SDK function set_first_level_parent_modifications()

Parameter	true	false
Result	The first item in the hierarchy of a modified item will also be exported	Only the modified item will be exported

same_parent_variants - with the call to the SDK function set_same_parent_variants_modifications()

Parameter	true	false
Result	All variants belonging to the same parent and a modified variant will be exported.	Only the modified variant will be exported.