Importing promotions

You can import the promotion created in external sources, so you can manage them in Synerise. The output of the import is a promotion added to the list of promotions in AI Hub icon AI Hub > Regular Promotions

Import methods

Before you proceed to importing promotions to Synerise, decide on the method of import and then see Requirements for the import method of your choice.

  • Simple import wizard - This method allows you to upload a .csv or .json file from your device and map the columns contained in the file with the equivalent parameters in your workspace.
    Recommended use: Single import of .csv or .json files.
  • Automation Hub - This method allows you to import a file from a server or from your device. The supported file formats include: .csv, .json, .jsonl, and .xml. You will be redirected to a workflow template which you can adjust to your business assumptions. The template contains a "Data Transformation Studio" node in which you can modify the imported data before the import to meet Synerise data standards. In the node, you can create a transformation from scratch or use a template from the transformations library.
    Recommended use: Imports of files stored in external servers (using HTTP and SFTP protocol), periodic imports;
  • Through API by using the Create or update promotion method.

Requirements


Click here to see Simple wizard import requirements
  • You need user permissions that grant you access to Simple Imports or/and Automation Hub.
  • Prepare a CSV or JSON file. It must contain the following parameters:
    • the ID of the promotion - it must be a string
    • type of redemption; accepted values: `FULL`, `PARTIAL`
    • the name of promotion that will be displayed on the list of promotions in Synerise UI (AI Hub icon AI Hub > Regular Promotions)
    • the name of the promotion visible to end-users
    • promotion type; accepted values: `GENERAL`, `MEMBERS_ONLY`, `HANDBILL`, `CUSTOM`
  • The file must be smaller than 5 GB (5 000 000 000 bytes).
  • In the Request body schema in the API Reference you can find a complete list of promotion information you can include in the file. The left column contains the parameter names and the right column contains information about allowed values.
Click here to see Automation import requirements
  • You need user permissions that grant you access to Simple Imports or/and Automation.
  • The imported file with promotions must contain the parameters listed below. If the file uses different names or values for the required parameters, you can align it with Synerise requirements by using a transformation in the Data Transformation Studio node in the workflow which imports promotions.
Parameter Allowed values type Required parameter name
The ID of the promotion any string `code`
Type of redemption `FULL`; `PARTIAL` `redeemType`
The name of the promotion displayed on the list of promotions in Synerise UI any string `headerName`
The name of the promotion visible to end-users any string `name`
The promotion type `GENERAL`; `MEMBERS_ONLY`; `HANDBILL`; `CUSTOM` `type`
Click here to see requirements for importing promotions through API

The requirements for importing through API are in Create or update promotion method documentation.

Tips for preparing a file

  • We recommend importing promotions in JSON files (through Automation Hub).

    • To include multiple values in one parameter, for example 3 colors in the colors parameter, do it in the following way:

      "colors": [
      "white",
      "green",
      "blue"
      ]
  • If you import a CSV file, these file metacharacters are recommended:

    • A character that marks the end of a column (delimiter): ,

    • A character that is used to contain the text (quotation mark): "
    • A character (escape character) that changes the default interpretation of a sign or string followed by the escape character: \
    • To include multiple values in one column, for example, 3 colors in the colors column, do it in the following way:
      color.0,color.1,color.2
      white,green,blue
  • For more details about parameters that can be defined for a promotion, you can check the API Reference.

Importing in Simple import wizard


  1. Go to Data Modeling Hub icon Data Modeling Hub > Imports > New import.
  2. As the data type for import, select Promotions.
  3. As the import method, select Import a local file.
  4. Upload the file with promotions:
    1. Upload a .csv or .json file by using the + Upload file or drop one here field.
    2. If you uploaded a CSV file, optionally, you can customize the file metacharacters by clicking the arrow down icon.
      1. From the Delimiter dropdown, select the character that marks the end of a column.
      2. From the Quotation mark dropdown list, select the characters that contain the text or data type.
      3. From the Escape character dropdown lists, select the character which changes the default interpretation of a character or a string followed by the escape character.
    3. If you uploaded a JSON file, optionally, in the JSON path field, enter a JSONPath expression that points to the data you want to import (for example, $.data.items[*]).
      • The expression must start with the $ character.
      • Each element that the expression returns is imported as a separate row. The rest of the file is discarded.
      • If you leave the field empty, the entire file is imported.
    4. Optionally, to check the data, click Preview data. If you entered a JSON path, the preview shows only the data at this path. If the path is invalid, the Can't process a file error is displayed. If the path doesn't point to any data in the file, the preview is empty.
    5. To proceed to the next step, click the Next button.
  5. From the Promotion parameters column, select the Synerise counterparts for the columns from the imported file. This way, you will point which parameters in Synerise will contain the promotion information from the imported file.
    • If you are not sure of the purpose of a parameter from the Promotion parameters list, see the Request schema body, where you can find the description of all parameters from this list.
    • To toggle between including/excluding a parameter, click Import column icon/Import column icon icons.
    • During the mapping process, you can't add new columns to the imported file.
    Mapping promotion parameters
    Mapping promotion parameters
  6. When mapping is completed, click Next.
    Result: A summary of import mapping is displayed.
  7. Verify the mapping summary. If it is correct, click Run import.
    Result: Promotions will be available on the list of promotions in AI Hub icon AI Hub > Regular Promotions and the import logs will be available in Data Modeling Hub icon Data Modeling Hub > Imports.

Importing in Automation


  1. Go to AI Hub icon AI Hub > Regular Promotions.
  2. Click Import.
  3. As the import method, select Import in Automation.
  4. From How are you going to deliver the file?, select the method of delivering the file.
  5. Click Go to import template.
    Result: You are redirected to a workflow template for importing promotions.
    Workflow template for importing promotions
    Workflow template for importing promotions
  6. Define the settings of the Scheduled Run node.
  7. Depending on the method of delivering the file, configure the settings of the node that you selected as the import method:
  8. If the data requires modification, configure the settings of the "Data Transformation Studio" node. If you have prepared a transformation for the data structure of the imported file, click Templates library and select it. If not, create it from scratch.
    You can remove this node if your data doesn't require transformation.
  9. The rest of the nodes in the default template don't require any further configuration.
  10. If your workflow is ready, click Save & Run.
    Result: Promotions will be available on the list of promotions in AI Hub icon AI Hub > Regular Promotions and the import logs will be available in Data Modeling Hub icon Data Modeling Hub > Imports.

Importing through API


To import promotions to Synerise through API, send a POST request to this endpoint.

Canonical URL: https://hub.synerise.com/docs/ai-hub/promotions/importing-promotions