Plentymarkets interface documentation

KeyFigure

Contracts

KeyFigureResultRepositoryContract

This interface allows you to search for key figures results.

Namespace

Plenty\Modules\BI\KeyFigure\Contracts

Methods
public searchKeyFigureResults($searchRequests):Plenty\Modules\BI\KeyFigure\Models\KeyFigureResultSearchResponse
Return type: KeyFigureResultSearchResponse

Search for key figure calculation results

Parameters

Name

Type

Description

$searchRequests

KeyFigureSearchRequests

Several key figure search requests

Models

KeyFigureConfig

The key figure config model represents the configuration of a key figure.

Namespace

Plenty\Modules\BI\KeyFigure\Models

Properties
Name Type Description

id

string

Id of this configuration

hash

string

Hash value to check for updates and avoid duplicate key figures with the same filters

plentyId

int

The plentymarkets system id

plentyIdHash

string

The plentymarkets system id hash

keyFigure

string

Key figure identifier

keyFigureCaption

string

Key figure caption

keyFigureName

string

User defined name

filter

KeyFigureFilter

Filter for calculating this key figure

targets

array

Contains the target figures

meta

KeyFigureMeta

Additional data

spreadSheetExport

KeyFigureSpreadSheetExport

Configuration data for the export of key figure results in a spread sheet document

direct

bool

This key figure triggers a direct calculation without saving the result

freeOfCharge

bool

Is this key figure free of charge

isGlobal

bool

updatedAt

string

Time of last change

createdAt

string

Time of creation

externalId

string

Identifier to assign the model

dimensions

array

List of existing dimensions

dimensionValues

array

List of dimension values

category

string

The translated category text of the keyfigure

aggregateFunctions

array

List of supported SQL aggregate functions

Methods
public toArray()

Returns this model as an array.

KeyFigureFilter

The key figure filter holds configured filters for a key figure calculation.

Namespace

Plenty\Modules\BI\KeyFigure\Models

Properties
Name Type Description

dataFilters

array

Filters in notation ['filterName' ⇒ ['operator' ⇒ 'eq', 'value' ⇒ 123]]

calculation

string

Selected calculation method

dimension

string

Data group to group the result

customUnit

string

Custom result unit

Methods
public toArray()

Returns this model as an array.

KeyFigureMeta

The key figure meta holds additional data.

Namespace

Plenty\Modules\BI\KeyFigure\Models

Properties
Name Type Description

comment

string

User comment

creatorUserId

int

Id of the user who created this key figure

creatorRealName

string

Real name of the user who created this key figure

isLimitEditing

bool

If true, then the key figure may only be edited by the creator

numberFormatLang

string

Language which determines the formatting of the numbers

formatResult

string

Format calculation result in SQL syntax

Methods
public toArray()

Returns this model as an array.

KeyFigureResult

Represents a key figure result

Namespace

Plenty\Modules\BI\KeyFigure\Models

Properties
Name Type Description

id

string

Primary key

plentyIdHash

string

System ID hash

configId

string

Id of the configuration of the key figure, followed by the calculation interval and The usage should be the exception, so this field usually resembles the content of idInterval.

scaleBasis

string

Time reference value of the key figure result.

dimension

string

The name of the dimension.

interval

string

Calculation interval.

primaryResult

float

The actual calculation result of the primary result data field.

furtherResult

string

If further results were calculated in addition to the primary result, these are included in this field as a JSON object. The fields are defined in the KeyFigure class.

calculatedAt

string

Date of calculation.

Methods
public toArray()

Returns this model as an array.

KeyFigureResultResponse

The model represent a key figure result in condensed form to the presentation.

Namespace

Plenty\Modules\BI\KeyFigure\Models

Properties
Name Type Description

id

string

The result ID

scaleBasis

string

Time reference value of the key figure result. The structure of scaleBasis depends on the time interval of the key figure. At the interval day is the structure: YYYYMMDD. For the interval month: YYYYMMM. In the case of year: YYYYY.

scaleBasisInt

string

Time reference value not formatted.

dimension

string

The name of the dimension.

primaryResult

float

The actual calculation result of the primary result data field.

furtherResult

string

If further results were calculated in addition to the primary result, these are included in this field as a JSON object. The fields are defined in the KeyFigure class.

resultUnit

string

Unit of the primary result.

target

float

Key figure target figure.

keyFigureName

string

Key figure name.

calculatedAt

string

Date of calculation.

Methods
public toArray()

Returns this model as an array.

KeyFigureResultSearchResponse

The model represent search result of key figure result search.

Namespace

Plenty\Modules\BI\KeyFigure\Models

Properties
Name Type Description

searchResultList

array

The list of found key figure result search result

Methods
public toArray()

Returns this model as an array.

KeyFigureResultSearchResult

The key figure result search result model combine key figure information with key figure search result.

Namespace

Plenty\Modules\BI\KeyFigure\Models

Properties
Name Type Description

keyFigureResults

array

Key figure result list

interval

string

Calculation interval.

searchId

string

Identification string to assign the result

keyFigure

string

Key figure identifier

error

array

Error occurred

query

string

Query for debugging

Methods
public toArray()

Returns this model as an array.

KeyFigureSearchRequest

The model holds filter information for a search query for key figures.

Namespace

Plenty\Modules\BI\KeyFigure\Models

Properties
Name Type Description

configId

string

Filter that restricts the search result to key figure results of key figure configuration id. The id of the key figure configuration is mandatory and must be specified, if no value is passed for id.

interval

string

Time interval in which the result was calculated: day, week, month, quarter, year.

dimension

string

This field will be removed until 11.2020

dimensions

array

Filter that restricts the search result to key figure results of one data group. The dimension must be specified.

scaleBasis

string

Filter restricts the list of results to items with a scale base time during the specified period. For the time interval day, a date or comma separated two dates (format: YYYYMMDD) can be specified. For the time interval week, several comma-separated days (YYYYMMDD) of different weeks can be specified. For the interval month, a comma separated list of months is expected e.g. 2020-01, 2020-02.

resultId

bool

Return ID of key figure result

resultUnit

bool

Return unit of the primary result.

target

bool

Return key figure target figure.

groupByDimension

bool

Groups the results by dimension

aggregateFunction

string

Define aggregate (group) function that will operate on key figure results. Default function: sum. Allowed values: sum, avg, count, max, min

itemsPerPage

int

Limits the number of results listed per page to a specific number. The number of variations to be listed per page must be specified. The default number of results is 12 and the maximum is 100.

page

int

Number of the requested page, default value: 1

searchId

string

Identification string to assign the result

calculatedAt

string

Filter that restricts the search result to key figure results which have been calculated as of this date (format: YYYY-MM-DD HH:II:SS)

sortBy

array

Sort the results options.

displayZeroPrimaryValue

bool

Display zero results on the UI

Methods
public toArray()

Returns this model as an array.

KeyFigureSearchRequests

The model represent several key figure search requests.

Namespace

Plenty\Modules\BI\KeyFigure\Models

Properties
Name Type Description

globalDataFilters

array

searchRequests

array

The list of key figure search requests

debug

bool

Methods
public toArray()

Returns this model as an array.

KeyFigureSpreadSheetExport

The key figure spread sheet export keeps configuration data for the export of key figure results in a spread sheet document.

Namespace

Plenty\Modules\BI\KeyFigure\Models

Properties
Name Type Description

spreadSheetURL

string

URL of the spread sheet document

exportMethod

string

Defines how the exported data is to be inserted in the document. Possible values: append, upsert.

timeInterval

string

Time interval in which the result data are to be aggregated. Possible values: day, week, month, quarter, year

exportColumns

array

List of column names to be exported

userId

int

Id of the user who created this spreadsheet configuration

lang

string

The language of the user

Methods
public toArray()

Returns this model as an array.

KeyFigureTarget

The key figure target day model contains the target figures for each weekday, week, month, quarter and year, which were stored for a key figure configuration

Namespace

Plenty\Modules\BI\KeyFigure\Models

Properties
Name Type Description

d1

float

Target value for Monday

d2

float

Target value for Tuesday

d3

float

Target value for Wednesday

d4

float

Target value for Thursday

d5

float

Target value for Friday

d6

float

Target value for Saturday

d7

float

Target value for Sunday

w

float

Target value for weeks

m1

float

Target value for January

m2

float

Target value for February

m3

float

Target value for March

m4

float

Target value for April

m5

float

Target value for May

m6

float

Target value for June

m7

float

Target value for July

m8

float

Target value for August

m9

float

Target value for September

m10

float

Target value for October

m11

float

Target value for November

m12

float

Target value for December

q1

float

Target value for first quarter

q2

float

Target value for second quarter

q3

float

Target value for third quarter

q4

float

Target value for fourth quarter

yl

float

Target value for last year

y

float

Target value for this year

Methods
public toArray()

Returns this model as an array.

KeyFigureTemplate

The key figure template model contains preview data of a key figure template

Namespace

Plenty\Modules\BI\KeyFigure\Models

Properties
Name Type Description

keyFigureName

string

User defined name

keyFigure

string

Key figure identifier

className

string

Template class name

Methods
public toArray()

Returns this model as an array.

RawData

Contracts

RawDataRepositoryContract

This interface allows you to get a list of generated raw data files

Namespace

Plenty\Modules\BI\RawData\Contracts

Methods
public searchRawData($dataName, $createdAtTimestamp, $processStatus, $itemsPerPage = 20, $sortOrder = "asc", $page = 1):Plenty\Modules\BI\RawData\Models\RawDataSearchResult
Return type: RawDataSearchResult

Get list of raw data. Valid filter combinations: (dataName), (dataName & processStatus), (createdAtTimestamp)

Parameters

Name

Type

Description

$dataName

string

Filter that restricts the search result to raw data files.

$createdAtTimestamp

int

Timestamp from when daily generated raw data are to be filtered. The maximum distance may not exceed one year.

$processStatus

string

Process status after which filtering is to take place

$itemsPerPage

int

The number of raw data files to be returned. The default number of files is 20 and the maximum is 100.

$sortOrder

string

Defines the sort order, possible values are: asc, desc. With simultaneous filtering to dataName, only the current result is sorted.

$page

int

public getRawDataFile($path):void

Get a raw data file from the storage, the storage path of the file must be specified.

Parameters

Name

Type

Description

$path

string

The raw data file path

public deleteRawData($dataName, $primaryIds):void
Parameters

Name

Type

Description

$dataName

string

$primaryIds

array

public getRawDataCreatorModels():array

Get list of all raw data creators

public getRawDataConfigs():Plenty\Modules\BI\RawData\Models\RawDataConfigs
Return type: RawDataConfigs

Returns list of all saved configurations

public updateRawDataConfigs($data):Plenty\Modules\BI\RawData\Models\RawDataConfigs
Return type: RawDataConfigs

Resets all saved raw data configurations with given data

Parameters

Name

Type

Description

$data

array

The configs data

Models

RawDataConfig

The BI raw data config model

Namespace

Plenty\Modules\BI\RawData\Models

Properties
Name Type Description

id

string

The raw data config id

plentyIdHash

string

The plentymarkets system id hash

dataName

string

The raw data name

active

bool

If active, raw data is generated daily

Methods
public toArray()

Returns this model as an array.

RawDataConfigs

List of all saved raw data configurations

Namespace

Plenty\Modules\BI\RawData\Models

Properties
Name Type Description

plentyIdHash

string

The plentymarkets system id hash

configs

array

List of all saved configurations

Methods
public toArray()

Returns this model as an array.

RawDataCreator

The BI raw data creator model

Namespace

Plenty\Modules\BI\RawData\Models

Properties
Name Type Description

dataName

string

Exclusive identifier for this raw data.

fileFormat

string

File format

limitPage

int

Number of data rows to be queried maximum per request.

limitDay

int

Number of data rows to be queried maximum per day.

earliestPossibleDataDate

string

Earliest possible date from which data should be requested.

filterType

string

Defines how this raw data is filtered.

dataUpdatedAtColumnName

string

Name of the column that contains the date of the last change to a data row.

defaultActive

bool

If true, then these raw data are collected independently of the user configuration.

interval

string

Interval in which this creator runs through

storableFromPlan

string

From which plan is this format created and provided.

processableFromPlan

string

From which plan will this data be transferred to plentyBI data warehouse database.

Methods
public toArray()

Returns this model as an array.

RawDataFile

The BI raw model

Namespace

Plenty\Modules\BI\RawData\Models

Properties
Name Type Description

id

string

The raw data id

plentyIdHash

string

The plentymarkets system id hash

dataName

string

The raw data name

processStatus

string

Status of data warehouse processing

shouldProcess

int

Specifies whether this file should be transferred to the data warehouse

cloudId

int

ID of source cloud

path

string

Storage path to raw data file

createdAt

string

Creation time of this raw data file

dataCreatedAt

string

Creation date of the data

Methods
public toArray()

Returns this model as an array.

RawDataSearchResult

The BI raw data search result model

Namespace

Plenty\Modules\BI\RawData\Models

Properties
Name Type Description

after

string

The last evaluated key as base64, provide that as the starting point for the next query (pagination).

searchResult

array

The raw data search result

Methods
public toArray()

Returns this model as an array.