These instructions are for new implementations of Luxiflux Zonal.

If you are migrating from our previous product, follow the instructions for migrating from Flash Indoor instead.


In this step you will:

  • Create a URL to launch Luxiflux Zonal.
  • Create a web API.
    • On your website
    • Which can be called by the Luxiflux Zonal tool
    • Which returns input to initialize the tool
  • Test it.


Step 2.1    Create an Input Web API URL


You need to create a web API on your website.

Decide what the URL for the API will be.


Example:

https://www.example.com/Luxiflux/Zonal/Input


Step 2.2    Build a URL to launch Luxiflux Zonal


Build a URL that launches Luxiflux Zonal.


The URL consists of the following parts (they are case sensitive):


https://v1-zonal-tools.luxiflux.comRequiredThe URL for the Luxiflux Zonal website.
AuthenticationUrlRequiredYou should have an authentication web API and its associated URL after completing the authentication step of these instructions.
InputMode

RequiredThe input mode (format) returned by the InputURL.
The value should be set to: JSON
InputUrlRequiredThe absolute URL that returns the input JSON data.

This should be a URL to a web API that generates and returns JSON as an HTTPS response.


In rare cases this might be a URL to an JSON file on a server (i.e. for testing).
InstanceKeyOptionalYou can specify a custom InstanceKey which is passed (in an HTTPS POST request) to the InputURL.  You can then use this Instance Key to modify the response of your Input Web API.

If the Instance Key is generic (always the same) each time the tool is launched, it can be omitted.


Example (broken into multiple lines for clarity):

http://v1-zonal-tools.luxiflux.com
?AuthenticationUrl=https://www.example.com/Luxiflux/Authentication
&InputMode=JSON
&InputUrl=https://www.example.com/Luxiflux/Zonal/Input
&InstanceKey=AnyInstanceKey


Example (no line breaks):

http://v1-zonal-tools.luxiflux.com?AuthenticationUrl=https://www.example.com/Luxiflux/Authentication&InputMode=JSON&InputUrl=https://www.example.com/Luxiflux/Zonal/Input&InstanceKey=AnyInstanceKey


Step 2.3   Strategy


Chances are that you want to launch the Luxiflux Zonal tool:

  • From different places on your website.
  • With different inputs depending on the context.

There are two ways to do this. 


Strategy A    Multiple Input URLs

When you want to launch Luxiflux Zonal with different inputs you can create multiple Input Web APIs.


Examples:

InputUrl=https://www.example.com/Luxiflux/Zonal/Input/ProductFamily1
InputUrl=https://www.example.com/Luxiflux/Zonal/Input/ProductFamily2
InputUrl=https://www.example.com/Luxiflux/Zonal/Input/ProductFamily3


Strategy B    Multiple Instance Keys

If you include the InstanceKey parameter in the launch URL, it is passed through to your web API.  You can then use it to determine how to dynamically change the output of you API.


Examples:

InstanceKey=ProductFamily1
InstanceKey=ProductFamily2
InstanceKey=ProductFamily3


Strategy C    Combined

You can also combine both strategies.  

You can create multiple APIs for the InputUrl parameter while also providing different values for the InstanceKey parameter.


Other Considerations

You should consider how website (and your website data/content) is organized, how often you intend to update your website, who needs to perform the updates, and the protocols and workflows required.


Step 2.4    Examine the Luxiflux Zonal Input Data


Please reference the following links:

  • LuxifluxZonal_InputExample
    • An example of the JSON response that must be returned by your Input Web API.
    • The JSON data returned by your Input Web API is used as input to initialize the Luxiflux Zonal tool.
  • LuxifluxZonal_InputComments
    • Contains comments and documentation for each item in the JSON data.


When the Luxiflux Zonal tool is launched it will send an HTTPS web request to the web API specified in the InputUrl.


If you include the InstanceKey parameter:

The tool will make a POST request to your web API with the following JSON data.

{
    "InstanceKey": "AnyInstanceKey"
}

Otherwise:

The tool will make a GET request to your web API.


The web API should return valid JSON with the specified data (see the example JSON file attatched to this article).


Step 2.5    Decide on Static and Dynamic Input Data


The JSON data your web API provides can be divided into two categories.

  • Static -- Data that is the same every time the tool is launched.
    • Typically includes logos, colors, units, etc.
  • Dynamic -- Data that changes every time the tool is launched. 
    • Typically includes photometry, etc.


You need to decide which portions of the JSON data will be static and dynamic in your case.

This can help you determine which strategy you employ when integrating the tool into your website.

Your web API needs to combine the static and dynamic portions of the data and provide the result as input to the tool.