Configuration

Setting phases

The application settings are divided into 2 phases. On Add Application and Configure Application. The first time an application is added to an instance, a user is created for the application, rights are set for the first time, and we receive a token for communication with our API for the first time. These phases are different in the first steps, so you have them drawn below for better orientation. We will get to the Configuration phase once we have successfully added the application to the instance and completed its setup. Here, too, we already have a token and a config that we can use token. And then we just modify the config application.

Add an application

After clicking on the Add button next to the application, a GET request occurs, namely to the basic url of the application, from where we get a JSON in response, if the status is HTTP 200. This JSON contains the initialization of our application. The JSON structure can be found in the Initialization section.

The rights of the application will be displayed here, and pressing the Continue button will create an incomplete user to whom the rights will be set. The request is sent to the POST, which points to the callback specified in our initialization, from which we receive the token. We need this token to communicate with the API. And according to him, we can find the settings that we created when we first added the application, this token can be used for all sales channels in our instance in which the application is set up.

HTTP Request - POST parameters

And JSON is returned to us, which must contain the ident parameter. We must specify here the name parameter, which will contain the name of the application and language, which will be an shortcut of the language of our application. The next parameter will be form, where we choose what type of form we want to generate on the Retailys side in the first step of the setup. We make this choice in the type parameter, which can contain string, textarea, select, checkbox and link. The name parameter specifies the name of the parameter, which will be returned to us in other Requests as a field filled with information about sales channels. Other parameters specify the settings of our element. As options, we will list all sales channels that we load via our API. Here you need to enter a field where the index will be the sales channel identifier and the value will be the sales channel name.

We will choose the same field format as the default_value values, but it is only necessary to specify sales channels for which the application has already been created, ie it already has a config stored in the database.

Finally, there is a need for a callback parameter, which will be the path that will lead to the next setup step. For example https://application.com/config-save, the path must lead to the application address, it cannot lead to another domain.

{
	"ident": {
		"name": "Example application configuration",
		"language": "en"
	},
	"form": [{
		"type": "select",
		"name": "channels",
		"multiple": true,
		"label": "Sales channels",
		"options": {
			"1": "Sales channel Eshop",
			"2": "Sales channel Marketplace"
		},
		"required": true,
		"default_value": null,
		"placeholder": "Please select at least one sales channel.",
		"select2": true
	}],
	"callback": "config-save"
}

After clicking the Continue button, an HTTP Request POST is sent, in which the parameter with the name we chose in the previous step for the form parameter as name is returned to us, which contains sales channel identifiers and the token parameter, which we use for communication with API.

HTTP Request - POST Parameters

Then we save the data to the database and if the saving is successful we have two options. We can either complete the configuration by returning JSON, which will contain the message parameter, which will contain a notification for the user, and a state parameter, which will contain the value success, in order to successfully complete the setup.

 return $this->json(
            [
                'message' => 'Successfully set up',
                'state' => 'success',
            ]
        );

Or we return a snippet, where we draw a template and pass it the necessary data, which is displayed in it, ie information about sales channels, their settings, or data already stored for sales channels in the application database. We will then return this snippet in JSON format, which will contain the snippet parameter and will contain the entire rendered template. We can use ordinary html in this template and we can also use styles here using Bootstrap 4.

Example in Symfony framework with twig template system

$snippet = $this->renderView('config/save.html.twig', [
        'config' => $config,
        'channelsData' => $channelsData,
        'configChannels' => $configChannels,
]);

return $this->json(
    [
        'snippet' => $snippet,
    ]
);

The data that we load into the template can then be displayed in the template. And they will also be sent to the data-url, which we must not forget to state somewhere at the end of the template, which will contain the path where we will store the necessary information in the database, ie the next step.

<div class="row">
  <div class="col-lg-3 col-xl-2 ">
   <input id="token" type="hidden" name="token" value="{{ config.token }}">
   {% for channelData in channelsData %}
   <div>
     <span>{{channelData.name}}</span>
   </div>
   {% endfor %}
  </div> 
<div id="callbackUrl" data-url="https://application.com/config-done"></div>

The resulting snippet can look different, for example it can take the form of tabs, switching with individual sales channels.

This cycle repeats until we decide to complete the configuration by returning a JSON with a successful message.

After successful setup, a message with a green background will appear in the administration, which we have set as the value of the message parameter, which will be returned to us at the end of the function that stores the data from the form in the application database.

Also, in the administration in the list of applications for the application we have just set, the icon will change from Add to Configuration.

Configuration application

After clicking on the Configuration button next to the application, two Requests occur. The first is the GET method and points to the base url of the application, from where it gets a JSON in response if the HTTP status is 200, in which the application is initialized. The JSON structure can be found in the Initialization section.

The second Request is sent a POST that points to the callback specified in our initialization, from which we receive the token. We need this token to communicate with the API. And according to him, we can find the settings that we created when we first added the application, this token can be used for all sales channels in our instance in which the application is set up.

HTTP Request - POST parameters

And JSON is returned to us, which must contain the ident parameter. We must specify here the name parameter, which will contain the name of the application and language, which will be an shortcut of the language of our application. The next parameter will be form, where we choose what type of form we want to generate on the Retailys side in the first step of the setup. We make this choice in the type parameter, which can contain string, textarea, select, checkbox and link. The name parameter specifies the name of the parameter, which will be returned to us in other Requests as a field filled with information about sales channels. Other parameters specify the settings of our element. As options, we will list all sales channels that we load via our API. Here you need to enter a field where the index will be the sales channel identifier and the value will be the sales channel name.

We will choose the same field format as the default_value values, but it is only necessary to specify sales channels for which the application has already been created, ie it already has a config stored in the database.

Finally, there is a need for a callback parameter, which will be the path that will lead to the next setup step. For example https://application.com/config-save, the path must lead to the application address, it cannot lead to another domain.

{
	"ident": {
		"name": "Example application configuration",
		"language": "en"
	},
	"form": [{
		"type": "select",
		"name": "channels",
		"multiple": true,
		"label": "Sales channels",
		"options": {
			"1": "Sales channel Eshop",
			"2": "Sales channel Marketplace"
		},
		"required": true,
		"default_value": null,
		"placeholder": "Please select at least one sales channel.",
		"select2": true
	}],
	"callback": "config-save"
}JSON

Application rights and settings

When entering the application settings, we can see the Application rights tab in the Retailys administration, this is an overview of the application user rights that we set in the initialization at the root address of the application.

In the second tab Settings we should get to the selection of sales channels on which we want to set the application, here we can list more sales channels at once.

After clicking the Update settings button, an HTTP Request POST is sent, in which the parameter with the name we chose in the previous step for the form parameter as name is returned to us, which contains sales channel identifiers and the token parameter, which we use for communication with API.

HTTP Request - POST Parameters

Then we save the data to the database and if the saving is successful we have two options. We can either complete the configuration by returning JSON, which will contain the message parameter, which will contain a notification for the user, and a state parameter, which will contain the value success, in order to successfully complete the setup.

 return $this->json(
            [
                'message' => 'Successfully set up',
                'state' => 'success',
            ]
        );

Or we return a snippet, where we draw a template and pass it the necessary data, which is displayed in it, ie information about sales channels, their settings, or data already stored for sales channels in the application database. We will then return this snippet in JSON format, which will contain the snippet parameter and will contain the entire rendered template. We can use ordinary html in this template and we can also use styles here using Bootstrap 4.

Example in Symfony framework with twig template system

$snippet = $this->renderView('config/save.html.twig', [
        'config' => $config,
        'channelsData' => $channelsData,
        'configChannels' => $configChannels,
]);

return $this->json(
    [
        'snippet' => $snippet,
    ]
);

The data that we load into the template can then be displayed in the template. And they will also HPHbe sent to the data-url, which we must not forget to state somewhere at the end of the template, which will contain the path where we will store the necessary information in the database, ie the next step.

<div class="row">
  <div class="col-lg-3 col-xl-2 ">
   <input id="token" type="hidden" name="token" value="{{ config.token }}">
   {% for channelData in channelsData %}
   <div>
     <span>{{channelData.name}}</span>
   </div>
   {% endfor %}
  </div> 
<div id="callbackUrl" data-url="https://application.com/config-done"></div>

The resulting snippet can look different, for example it can take the form of tabs, switching with individual sales channels.

This cycle repeats until we decide to complete the configuration by returning a JSON with a successful message.

After successful setup, a message with a green background will appear in the administration, which we have set as the value of the message parameter, which will be returned to us at the end of the function that stores the data from the form in the application database.