Defining interface services

To define an interface service:

  1. Select Configuration > Common > Interface Services.
  2. Click New.
  3. In the New Interface Service window, specify this information:
    Interface Type
    Select the interface type. These are the options:
    • API
    • CSV
    • Database
    • EXCEL
    Data Entity
    Select the data entity that must be mapped to the interface. The types of data entities:
    • Calendar
    • Code List
    • Scenario Value
      Note: If you select this option, you must specify the Import Behavior.
    • Transactional Data
    • SCV Table
    • AS Table
    • Market Intelligence
    • Planning Engine
    Interface Direction
    Based on your previous selections, specify Export, Import, or Import and Export, as required.
    Column per Measure
    If this check box is selected, each measure is displayed in a new column in the interface. You can add new rows and measures with these dimensions, in the Mappings tab:
    • Item
    • Location
    • Calendar Period

    If this check box is cleared, the list of dimensions in the Mappings tab is fixed to five columns with these dimensions:

    • Item
    • Location
    • Calendar Period
    • Measure
    • Value
    Note: You can view this field only if Data Entity is set to Scenario Value, for all the interface types.
  4. Click OK. The list is replaced with a details form, in which the values of the Interface Type and Data Entity fields are based on your selection.
  5. Based on the selected data entity, specify this information:
    Module
    The module to which the interface service is linked. Select the appropriate module.
    Target Code List
    The name of the data source used as part of the interface service.
  6. Specify this information:
    Name
    Specify the name of the interpolation interface service.
    Display Name
    Specify the name to be displayed in the application. This is an optional field.
    System
    This is a read-only field.
    Data Source
    The name of the data source used as part of the interface service.
  7. Based on the Interface Type you selected, specify the required information:
    If you select CSV:
    Option Description
    Files The name of the CSV file used as part of the interface service.
    Field Names in Header Row

    Select this check box to indicate either of the following:

    • The first row of the import file contains field labels and can be skipped.
    • The first row of the export file must contain field headers.
    Calendar Period Definition Indicates if calendar periods are exported using the bucket start date, bucket end date, or the bucket name defined in the calendar format, for example, FY10 M03.
    If you select Database and, for the Source, use the default Table selection, specify this information:
    Option Description
    Tables The name of the table used as part of the interface service.
    Import Filter

    Specify a filter on the data passed using the interface service, else all records of the selected source table are applicable. The text must be in the format of a standard SQL WHERE clause, although the WHERE keyword is implicit.

    To filter data using dimensions, you can also use these variables:

    • %cycle%: Cycle name
    • %cycleperiod%: Cycle period label
    • %cycleperiod-Startdate%: The start date of the current cycle period bucket (at Cycle.Periodicity), in the required date format. This is not the date on which the cycle period is started.
    • %cycleperiod-Enddate%: The end date of the current cycle period bucket (at Cycle.Periodicity), in the required date format. This is not the date the cycle period is completed or the end of the cycle period horizon.
    • %horizon-start%: The start date of the cycle period horizon, in the required date format; that is the first (oldest) base period within the current cycle period.
    • %horizon-end%: The end date of the cycle period horizon, in the required date format; that is the last (newest) base period within the current cycle period.
    • %scenario%: scenario name

    Examples:

    CHAN_ID <> 'TOTAL' AND End_date > %CyclePeriod-StartDate% or PROD_GROUP = %scenario% AND PERIOD >= %horizon-start% AND PERIOD <= %horizon-end%
    If you select Database > Source > Query:
    Option Description
    Query Specify an SQL statement, and click Verify to validate the query text.
    Note:  If the query is successfully validated, the returned fields are stored for use in the Mappings and Import / Export Measures tabs, which allows you to select the fields for mapping.

    Otherwise, you must manually add the fields in the data source, for this interface.

  8. For any of the interface types:
    Calendar Period Definition
    Indicates whether calendar periods are exported using the bucket start date, bucket end date, or the bucket name defined in the calendar format, for example, FY10 M03.
  9. Select the Clear Unchanged Scenario Values check box to reset the scenario values that are not modified, after importing the data based on the measure filter.
    Note:  If the measure filter is specified, all the unchanged values for measures in the filter are reset. If not specified, all the unchanged values for measures that are updated during the import are reset.
  10. The Mappings tab contains a list of dimensions to be mapped and module settings, if applicable. On this tab, change the related field labels as required.
  11. The Import / Export Measures tab contains a list of measures (rows) that act as the source or destination of the transfer, and the corresponding identifier in the interface service. On this tab, click New to enter measures that act as a filter for the interface service, only importing or exporting the measures defined here.
  12. For interface type Database, the additional Export Constants tab lists the applicable constant data to be exported. On this tab, change the related field labels and values as required. The export constants specified on this tab can be used to export multiple scenarios with a single interface definition using the Import Filter variables. For example, if the export constant uses the %scenario% variable, this variable can use a single interface definition to export multiple scenarios.

    To filter data using against dimensions, you can also use these variables:

    • %cycle%: Cycle name
    • %cycleperiod%: Cycle period label
    • %cycleperiod-Startdate%: The start date of the current cycle period bucket (at Cycle.Periodicity), in the required date format. This is not the date the cycle period is started.
    • %cycleperiod-Enddate%: The end date of the current cycle period bucket (at Cycle.Periodicity), in the required date format. This is not the date the cycle period is completed or the end of the cycle period horizon.
    • %horizon-start%: The start date of the cycle period horizon, in the required date format; that is the first (oldest) base period within the current cycle period.
    • %horizon-end%: The end date of the cycle period horizon, in the required date format; that is the last (newest) base period within the current cycle period.
    • %scenario%: Scenario name
  13. Click Submit.