0 Introduction

Here you will find all information to get started using TiCon4 REST API. We'll start with an example how to read time element data from TiCon and how to write data back to TiCon. These first two chapters will enable you to do standard work.

If you want to know more about the data structure and detailed concepts of the API you should continue reading all the following chapters. Have fun using our API.

1 Reading data from TiCon

1.1 Version information

This is the simplest call, that also does not require authorization, to get details about the TiCon REST API version.

{{ServerAddress}}/ticon-web/services/management/version

Returns

Details about current TiCon REST API version and used TiCon4 database version. If there is an error while connection to the database, the error message will appear here, a detailed message can be obtained from Azure insight or Windows Event viewer.

{
  "serverTime": "2023-11-27T08:59:45",
  "version": {
    "apiVersion": "4.08.09.1977 [.NETCoreApp,Version=v6.0]",
    "dbVersion": "TiCon408Praes [4.08.06.0007]"
  }
}

1.2 Configuration information

This is the simplest call, that also does not require authorization, to get details about the TiCon REST API configuration.

{{ServerAddress}}/ticon-web/services/management/configuration

Returns

Details about current TiCon REST API configuration.

{
  "serverTime": "2023-11-27T09:28:51.731Z",
  "configuration": {
    "sqlConnectionTimeout": "15",
    "sqlCommandTimeoutInSeconds": "30",
    "sqlConfiguration": [
      {
        "key": "DataSource",
        "value": "(LocalDB)\\MSSQLLocalDB"
      },
      {
        "key": "ApplicationName",
        "value": "TiCon4"
      },
      {
        "key": "InitialCatalog",
        "value": "TiCon407"
      },
      {
        "key": "AttachDBFilename",
        "value": "C:\\ProgramData\\MTM\\TiCon 4.07\\db\\TiCon4.mdf"
      }
    ]
  }
}

Remarks
You can configure the SQL command timeout, if it is necessary, e.g. if you get a SQL Client timeout exception. Beware this parameter is not the SQL connection timeout value! Edit the SqlCommandTimeoutInSeconds option in the appsettings.json file, don't forget to restart your service, after you change the value.

1.3 Languages

This call needs also no authorization, to get information about all languages.

{{ServerAddress}}/ticon-web/services/management/languages

Returns

A list of all installed languages in the TiCon4 database. If you use the parameter lang, you can use one displayed language to get all texts in this specific language.

{
  "serverTime": "2023-11-27T09:28:51.731Z",
  "languages": [
    {
      "languageCode": "de",
      "languageDescription": "Deutsch",
      "countryCode": "DE",
      "countryDescription": "Deutschland"
    },
    {
      "languageCode": "en",
      "languageDescription": "English",
      "countryCode": "US",
      "countryDescription": "United States"
    }
  ]
}

1.4 Time elements

To retrieve basic data for Time Elements, also known as analyses, you can use the following call:

{{ServerAddress}}/ticon-web/services/data/time-elements?code={{code}}&lang=en-US&expand[description]&expand[times]&expand[elementType][description]&expand[elementStatus][description]&expand[structure][row][description]&expand[structure][row][element][times]&expand[structure][row][criterion][description]&expand[defaultcriterion][description]

The table below lists where to find the data numbered in the TiCon screenshot.

No.	Content	Property Name and Remarks
1	Code of time element	entities[0].code
2	Basic time of element	entities[0].times.tg
3	Other times of element	entities[0].times.XXX
4	Description of element	entities[0].description.text
5	Type of element	Search for entities[0].elementTypeUid in expanded[] (expanded[x].uid = elementTypeUid), then read expanded[x].code and expanded[x].description.text
6	Status of element	Search for entities[0].elementStatusUid search in expanded[] (expanded[x].uid = elementStatusUid), then expanded[x].code and expanded[x].description.text
7	Starts	entities[0].begin.text
8	Includes	entities[0].content.text
9	Ends	entities[0].end.text
10	Criterions of element	entities[0].criteria[].row.elementCriterionUid element criteria structure row (expanded[x].elementCriterionCode and expanded[x].(textValue or numberValue))

Remarks
A Time element can have a short code, entities[0].shortcode, depending on the chosen analysis method.
All displayed times in TiCon4 REST API will be shown in TMU.

No.	Content	Property Name and Remarks
10	Order number of structure row	entities[0].structure[].row.orderNumber
11	Description of usage	entities[0].structure[].row.description.text
12	Code of used element	Search for entities[0].structure[].row.elementUid in expanded[] (expanded[x].uid = structure[].row.elementUid), then read expanded[x].code
13	Index of used element	analogous to 12, then read expanded[x].index
14	Variant of used element	analogous to 12, then read expanded[x].variant
15	Section number	entities[0].structure[].row.sectionNumber
16	Section factor string	entities[0].structure[].row.sectionFactor
17	Basic time of used element	entities[0].structure[].row.times.tg
18	Setup time of used element	entities[0].structure[].row.times.tr
19	Factorstring of usage	use entities[0].structure[].row.factor for display (can be a formula) and entities[0].structure[].row.factorValue (is always a calculated number including the section factor and other factors) for calculations
20	Total basic time of used element	entities[0].structure[].row.totaltimes.tg
21	Total setup time of used element	entities[0}.structure[].row.totaltimes.tr
22	Indictors	Search for entities[0].structure[].row.criterionUids[0] in expanded (expanded[x].uid = structure[].row.criterionUids[0]), then read expanded[x].color for the color and expanded[x].code for the code
23	Code of sections	entities[0].code + "-" + entities[0].structure[].row.sectionNumber in expanded[] (expanded[x].uid = structure[].row.elementUid), then read expanded[x].code
24	Section number	entities[0].structure[].row.sectionNumber
25	Section factor string	entities[0].structure[].row.sectionFactor
26	Basic time of used elements in section	analogous to 17
27	Setup time of used elements in section	analogous to 18
28	Total basic time of section	analogous to 20
29	Total setup time of section	analogous to 21
30	Total basic time of whole structure	sum of all structure basic times
31	Total setup time of whole structure	sum of all structure setup times

You will find three different types of lines: Section lines, Element lines and lines containing just a comment. These lines can be identified as follows:

• Element lines structure[].row.rowType = "REFERENCE" and structure[].row.typeEnum = "Element"
• Comment lines structure[].row.rowType = "REFERENCE" and structure[].row.typeEnum = "Text"
• Section lines structure[].row.rowType = "SECTION_HEADER"

1.5 Detailed documentation

Here you can see the current TiCon4 REST API class structure, with inheritance hierarchy and important enum structures.

A detailed REST API documentation with description of data schema and possible query parameters can be found here.

1.6 Filtering

The TiCon REST API offers different ways to filter TiCon4 elements. The most common use case is searching by code, index and variant:

{{ServerAddress}}/ticon-web/services/data/time-elements?code={{code}}&index={{index}}&variant={{variant}}&lang=en-US&expand[description]

It is also possible to search TiCon4 elements by folder properties, like ID or path:

{{ServerAddress}}/ticon-web/services/data/time-elements?folderUids={{uid,uid}}&expand[description]&expand[folder][description]
{{ServerAddress}}/ticon-web/services/data/time-elements?folderpath={{path}}&expand[description]&expand[folder][description]

If you want to search recursive thru the folder path, add foldersrecursive=true to your parameters:

{{ServerAddress}}/ticon-web/services/data/time-elements?folderpath={{path}}&expand[description]&expand[folder][description]&foldersrecursive=true

It is not recommended to use folderUids and folderPath at the same time!

A most important use case is to search elements by their status. You can filter TiCon4 elements lower than a certain status lt, or by status greater than or equal, gte:

{{ServerAddress}}/ticon-web/services/data/time-elements?expand[elementstatus]&statuslt={{elementStatus}}
{{ServerAddress}}/ticon-web/services/data/time-elements?expand[elementstatus]&statusgle={{elementStatus}}

The next section shows more examples of how you can filter in the TiCon4 REST API.

{{ServerAddress}}/ticon-web/services/data/time-elements?expand[description]&expand[elementconfiguration]&ownercodes={{code}},{{code}}
{{ServerAddress}}/ticon-web/services/data/time-elements?expand[description]&expand[elementconfiguration]&owneruids={{uid}},{{uid}}
{{ServerAddress}}/ticon-web/services/data/time-elements?expand[description]&expand[elementconfiguration]&eccCodes={{code}},{{code}}
{{ServerAddress}}/ticon-web/services/data/time-elements?expand[description]&expand[elementconfiguration]&elementconfiguids={{uid}},{{uid}}

1.6.1 Joker characters

It is possible to use joker characters in filtering, e.g. as many or replace by one any character. Possible placeholders are

• %, * Placeholders for many any characters
• _, ? Placeholders for one any character

Joker characters only working, when *Wildcards parameter is set to true. At next some examples.

{{ServerAddress}}/ticon-web/services/data/time-elements?codeWildcards=true&code=3000K_.....5
{{ServerAddress}}/ticon-web/services/data/time-elements?codeWildcards=true&code=3000K*
{{ServerAddress}}/ticon-web/services/data/time-elements?codeWildcards=true&code=3000??.....5

1.7 Advanced search in TiCon REST API

The TiCon REST API offers an advanced search mechanism. To call the advanced searching, you have to use the following URL, it is necessary to create a search filter item as JSON in the request body and send it as POST to the server:

{{ServerAddress}}/ticon-web/services/data/search
{{ServerAddress}}/ticon-web/services/data/search?expand[times]&sortby=index,description desc

The default order behaviour of advanced search is Code, Index, Variant, but you can change this by set sortby keyword. If you want sort your results by ModifyUser.Code, you have to set the query parameter dueDate, see exmaple.

{{ServerAddress}}/ticon-web/services/data/search?expand[times]&sortby=modifyuser.code,description desc&dueDate=2023-5-15

Caution: very complex filter configurations can cause connection timeouts!

Remarks
If the search JSON is not valid, the TiCon REST API throws an exception.
If you want to show standard times or the descriptions, use the expand parameter, see chapter 6.5

1.7.1 Different filter types

The TiCon REST API advanced search supports different filter types:

• TimeFilter
• ReferenceFilter
• TagFilter
• FolderFilter
• ElementCriteriaFilter
• CodeIndexVariantFilter
• IndicatorFilter
• EawsEvauluationFilter
• JournalFilter
• DescriptionFilter
• ElementTextsFilter
• ElementClassConfigurationFilter
• ElementTypeStatusFilter
• ShortCodeFilter
• MasterFilter
• DeletedFilter

Every filter type has his own configuration framework. At first you have to set the filterType property, afterward defining the rows property, which can be very complex.

Remarks
When you use the DeletedFilter no other filter type is possible, otherwise the TiCon REST API throws an exception.

1.7.2 The Master filter

The behavior of the master filter is different from the other filter types. Only the stringValue and the language are allowed. In addition, there is a Property searchedField, which may have the following properties:

• MasterData - the string is searched in Code, Index, Variant and Description
• TimeData - the string is searched in Begin, Content, End and Limit of TimeElements and HWD-Elements
• All - is a combination of MasterData and TimeData

The compare operator is always contains, no other operators are valid. Wildcards are not allowed in this filter type and only one row is approved. The master filter can combined with the other filter types, please keep in mind, the logical operator between the other filter types and the master filter is always AND - (Code OR Index Or Variant OR Description) AND other filter type.

Examples:

[
  {
    "filterType": "masterfilter",
    "rows": [
      {
        "stringValue": "aufnehmen",
        "language": "de-DE",
        "searchedFields": "MasterData"
      }
    ]
  }
]

or

[
  {
    "filterType": "masterfilter",
    "rows": [
      {
        "stringValue": "leicht",
        "language": "de-DE",
        "searchedFields": "All"
      }
    ]
  },
  {
    "filterType": "codeindexvariantfilter",
    "rows": [
      {
        "code": "3000AA",
        "compareOperator": "contains"
      }
    ]
  }
]

The second example searches in Code OR Index OR Variant OR Description that contains the word leicht AND the Code contains 3000AA.

1.7.3 Examples

1.7.3.1 Search by code, index, variant

To search by code, index and variant with wildcards, your mask in TiCon looks like the screenshot shows.

The corresponding JSON for the TiCon REST API is very easy.

[
  {
    "filterType": "codeIndexVariantFilter",
    "rows": [
      {
        "code": "2000A*",
        "compareOperator": "Like"
      }
    ]
  }
]

When you add another row, your JSON looks as following:

[
  {
    "filterType": "codeIndexVariantFilter",
    "rows": [
      {
        "code": "2000A*",
        "compareOperator": "Like"
      },
      {
        "code": "AN",
        "index": "2",
        "compareOperator": "Equals"
      }
    ]
  }
]

Every new row in the filter definition is an OR nexus. When you add a new filterType with rows, it is an AND nexus.

1.7.3.2 Search by code or index or variant and description

If you want a filter to search by code 2000A* OR index OR variant AND a description contains "walk", the TiCon search mask looks as follows:

The TiCon REST API JSON is the following:

[
  {
    "filterType": "codeIndexVariantFilter",
    "rows": [
      {
        "code": "2000A*",
        "compareOperator": "Like"
      },
      {
        "index": "1",
        "compareOperator": "Like"
      },
      {
        "variant": "2",
        "compareOperator": "Like"
      }
    ]
  },
  {
    "filterType": "descriptionFilter",
    "rows": [
      {
        "description": {
          "stringValue": "walk",
          "language": "en-US",
          "compareOperator": "Contains"
        }
      }
    ]
  }
]

1.7.3.3 Search by code or index or variant OR description

You can change the AND behavior in the upper example, by setting the andCompare property to false. To do that, add this keyword to the URL:

{{ServerAddress}}/ticon-web/services/data/search?expand[times]&sortby=modifyuser.code,description desc&dueDate=2023-5-15&andCompare=false

1.7.3.4 Search element type 'XY' in folder 'XX'

The next example looks like the screenshot below, it is a search by element type and folder.

The user wants to search by an Element type of "E.EAD" in folders "EAWS", "FH", "GH", "SA", "UT", "V" and "WT". The following JSON definition is valid in this case.

[
  {
    "filterType": "elementClassConfigurationFilter",
    "rows": [
      {
        "code": "e.ead"
      }
    ]
  },
  {
    "filterType": "folderFilter",
    "rows": [
      {
        "uid": "Folder-25"
      },
      {
        "uid": "Folder-26"
      },
      {
        "path": "\"TiCon\\F\\UD\\EAWS\\GH\""
      },
      {
        "uid": "Folder-30"
      }
    ]
  }
]

1.7.3.5 Search element type 'XY' in folder 'XX' and change date 'xxxx-xx-xx'

You create the following search mask in TiCon, the search parts are element type, folder and change information.

The JSON body for the TiCon REST API is a bit complex, let's take a look.

[
  {
    "filterType": "ElementClassConfigurationFilter",
    "rows": [
      {
        "code": "R.TSY"
      }
    ]
  },
  {
    "filterType": "folderFilter",
    "rows": [
      {
        "code": "UD"
      }
    ]
  },
  {
    "filterType": "journalFilter",
    "rows": [
      {
        "searchPair": {
          "journalEntry": {
            "journalFilterType": "None"
          },
          "journalDate": {
            "stringValue": "2019-4-22",
            "compareOperator": "greaterThan",
            "journalFilterType": "changeDate"
          }
        }
      }
    ]
  }
]

Remarks
The search filter journalFilter needs a row pair, called searchPair. Inside this clause you have to define a journalEntry and a journalDate property. As you can see, you have to set the journalFilterType, here is a list of all possibilities.

• None
• Owner
• Creator
• Changer
• CreationDate
• ChangeDate
• ChangeCode
• ChangeReason
• ChangeType

1.7.3.6 Search for elements in folder 'XY' with element criterion 'X'

In TiCon you have to create the following search mask, take a look at the screenshot.

We will search for elements in folder "TEST" where the criterion Department is exactly "X". The TiCon REST API JSON is as following:

[
  {
    "filterType": "folderFilter",
    "rows": [
      {
        "path": "\"TiCon\\F\\UD\\TEST\""
      }
    ]
  },
  {
    "filterType": "elementCriteriaFilter",
    "rows": [
      {
        "code": "dp",
        "compareOperator": "Equals",
        "elementCriteriaType": "String",
        "stringValue": "X"
      }
    ]
  }
]

Remarks
The elementCriteriaFilter needs an elementCriteriaType, because in the critias some different types exist.

• String
• Number
• Date
• List
• Bool
• Group

When the elementCriteriaType is a list value, the JSON looks like this.

{
  "filterType": "elementCriteriaFilter",
  "rows": [
    {
      "code": "GD",
      "compareOperator": "NotEquals",
      "elementCriteriaType": "List",
      "fixedCriterionValue": {
        "code": "m"
      }
    }
  ]
}

When you set a DateTime value, be careful, that it is in a valid writing form. The schema is always year-month-day hour:minute:second (yyyy-MM-dd hh:mm:ss), independently from locale language settings. All times are in GMT. Take a look:

{
  "filterType": "elementCriteriaFilter",
  "rows": [
    {
      "code": "DATE",
      "compareOperator": "LessThan",
      "elementCriteriaType": "Date",
      "stringValue": "2023-4-9"
    }
  ]
}

2 Writing data to TiCon

As TiCon supports multilingualism, writing data to TiCon creates text in all installed languages (installed in TiCon that is) with the leading language being the login language. So be sure to add the leading/login language via the lang query parameter (i.e. {{ServerAddress}}/ticon-web/services/data/time-elements?lang=en-US) or via header (first value in Accept-Language) to each call. Otherwise the language (culture) of the servers OS is the leading/login language. This can lead to unforeseen errors i.e. when the servers culture is not installed in TiCon.

2.1 Time elements

The next chapter will describe how to create a new Time element with the TiCon4 REST API. To create a new element, you have to create a JSON structure in the request body and send it as a POST request. Following properties are mandatory:

• Code
• folderUid
• elementConfigurationUid

To create a new Time element with the TiCon4 REST API you have to call the following URL:

{{ServerAddress}}/ticon-web/services/data/time-elements

2.1.1 Simple example

At first a very simple example, to create a Time element with code and a certain element class configuration, the user needs the minimum permission write.

[
  {
    "code": "AN.1...3",
    "folderUid": "Folder-130",
    "elementConfigurationUid": "ElementClassConfiguration-100013"
  }
]

The table below lists where to find the data numbered in the TiCon screenshot.

No.	Content	Property Name and Remarks
1	Code of time element	entity.code
2	Folder to save the element	entity.folderUid you need a folder, you have the permission write, to get folders see chapter 6.6.3
3	Element class configuration of element	entity.elementConfigurationUid you need the Uid of the element class configuration, see chapter 6.6.4

2.1.2 Text handle example

Here an example to create a Time element with code, description, begin, content, end and limit, this shows you how to handle text fields in the TiCon4 REST API:

[
  {
    "code": "AN.1...3",
    "folderUid": "Folder-130",
    "ownerUid": "Account-2",
    "elementConfigurationUid": "ElementClassConfiguration-100013",
    "description": {
      "language": "en-US",
      "text": "Insert condenser module, motor bearing and condenser motor"
    },
    "begin": {
      "language": "en-US",
      "text": "with walking to condenser module"
    },
    "end": {
      "language": "en-US",
      "text": "After returning torque screwdriver"
    },
    "limit": {
      "language": "en-US",
      "text": "all activities within 2-m range"
    },
    "content": {
      "language": "en-US",
      "text": "Insert condenser module into frame, grease motor bearing and insert condenser module..."
    }
  }
]

No.	Content	Property Name and Remarks
1	Code of time element	entity.code
2	Description of element	entity.description.text
3	Starts of element	entity.begin.text
4	Includes of element	entity.content.text
5	Ends of element	entity.end.text
6	Limitations of element	entity.limit.text

Remarks
When you work with text fields, remember to add the language property!

2.1.3 Full example

Here a full example, that includes a very simple structure.

[
  {
    "code": "AN.1...3",
    "folderUid": "Folder-130",
    "ownerUid": "Account-2",
    "elementConfigurationUid": "ElementClassConfiguration-100013",
    "description": {
      "language": "en-US",
      "text": "Insert condenser module, motor bearing and condenser motor",
      "isSource": true
    },
    "begin": {
      "language": "en-US",
      "text": "with walking to condenser module",
      "isSource": true
    },
    "end": {
      "language": "en-US",
      "text": "After returning torque screwdriver",
      "isSource": true
    },
    "limit": {
      "language": "en-US",
      "text": "all activities within 2-m range"
    },
    "content": {
      "language": "en-US",
      "text": "Insert condenser module into frame, grease motor bearing and insert condenser module..."
    },
    "times": {
      "ttbUser": 3416.6666666666665,
      "ttu": 3416.6666666666665,
      "ttuUser": 2500.6666666666665,
      "tg": 3416.6666666666665,
      "te": 3416.6666666666665,
      "t": 3416.6666666666665
    },
    "elementStatusUid": "ElementStatus-7",
    "elementTypeUid": "ElementType-1",
    "workorganizationType": "None",
    "structure": [
      {
        "row": {
          "elementUid": "Element-1005",
          "factor": "2",
          "ordernumber": 1,
          "typeEnum": "Element",
          "description": {
            "language": "en-US",
            "text": "Walk to motor and back"
          }
        }
      },
      {
        "row": {
          "elementUid": "Element-1005",
          "factor": "1",
          "ordernumber": 2,
          "typeEnum": "Element",
          "description": {
            "language": "en-US",
            "text": "2 screws"
          },
          "criterionUids": [
            {
              "key": "1",
              "value": "IndicatorCriterion-10003"
            }
          ]
        }
      },
      {
        "row": {
          "elementUid": "Element-1004",
          "factor": "3",
          "ordernumber": 3,
          "typeEnum": "Element",
          "description": {
            "language": "en-US",
            "text": "Torque screwdriver"
          },
          "criterionUids": [
            {
              "key": "1",
              "value": "IndicatorCriterion-10004"
            }
          ]
        }
      },
      {
        "row": {
          "elementUid": "Element-13605",
          "factor": "1.5",
          "ordernumber": 4,
          "typeEnum": "Element",
          "description": {
            "language": "en-US",
            "text": "stoop for deep-drawing film condenser module"
          },
          "criterionUids": [
            {
              "key": "1",
              "value": "IndicatorCriterion-10004"
            }
          ]
        }
      }
    ]
  }
]

No.	Content	Property Name and Remarks
1	Code of time element	entity.code
2	Description of element	entity.description.text
3	Type of element	entity.elementTypeUid you need the Uid of element type, which Uids are possible, see chapter 6.6.5
4	Status of element	entity.elementStatusUid you need the Uid of element status, which Uids are possible, see chapter 6.6.6
5	Starts of element	entity.begin.text
6	Includes of element	entity.content.text
7	Ends of element	entity.end.text
8	Limitations of element	entity.limit.text

No.	Content	Property Name and Remarks
9	Order number of structure row	entity.structure[].row.orderNumer
10	Description of used row element	entity.structure[].row.description.text
11	Code of used element	entity.structure[].row.elementUid and you have to set the typeEnum property to Element
12	Factorstring of usage	entity.structure[].row.factor
13	Indicators	entity.structure[].row.criterionUids[].IndicatorCriterion you need the Uid of indicator criterion, see chapter 6.6.7

No.	Content	Property Name and Remarks
14	Manual time	entity.times.ttbUser
15	Process time	entity.times.ttuUser
16	Basic time	is the sum from entity.times.ttbUser + entity.times.ttuUser

Remarks
Please remember, all times have to be set in TMU.

2.1.4 Time element with an formula element in structure example

At next, here is a complex example to create a time element with an formula element in structure. Some formula parameters will be overriden in this example, see formulaValues in the structure row, you will find a variable definition (variables), which will override a formula value too.

[
  {
    "code": "AN.1...2",
    "folderUid": "Folder-166",
    "ownerUid": "Account-2",
    "elementConfigurationUid": "ElementClassConfiguration-4101",
    "description": {
      "language": "en-US",
      "text": "Time element with formula over Rest API",
      "isSource": true
    },
    "begin": {
      "language": "en-US",
      "text": "with walking to condenser module",
      "isSource": true
    },
    "end": {
      "language": "en-US",
      "text": "After returning torque screwdriver",
      "isSource": true
    },
    "limit": {
      "language": "en-US",
      "text": "all activities within 2-m range"
    },
    "content": {
      "language": "en-US",
      "text": "Insert condenser module into frame, grease motor bearing and insert condenser module..."
    },
    "times": {
      "ttu": 48807531.97912965,
      "ttb": 178,
      "ttuUser": 2500.6666666666665,
      "tg": 48807758.97912965,
      "te": 48807758.97912965,
      "t": 48807758.97912965
    },
    "elementStatusUid": "ElementStatus-7",
    "elementTypeUid": "ElementType-1",
    "workorganizationType": "None",
    "variables": [
      {
        "row": {
          "code": "EV",
          "typeEnum": "Default",
          "value": 4
        }
      }
    ],
    "structure": [
      {
        "row": {
          "elementUid": "Element-14147",
          "factor": "3",
          "typeEnum": "FormulaElement",
          "ordernumber": 1,
          "description": {
            "language": "en-US",
            "text": "Formula with Rest API"
          },
          "formulaValues": [
            {
              "row": {
                "ordernumber": 5,
                "calculation": "pts",
                "typeEnum": "FormulaValue"
              }
            },
            {
              "row": {
                "calculation": "mix",
                "ordernumber": 6,
                "typeEnum": "FormulaValue"
              }
            },
            {
              "row": {
                "ordernumber": 8,
                "calculation": "13",
                "typeEnum": "FormulaValue"
              }
            }
          ]
        }
      },
      {
        "row": {
          "times": {
            "ttb": 25,
            "tg": 25,
            "te": 25,
          },
          "elementUid": "Element-259",
          "factor": "2",
          "factorValue": 2,
          "customFactor": "1",
          "orderNumber": 2,
          "typeEnum": "Element"
        }
      },
      {
        "row": {
          "elementUid": "Element-14145",
          "factor": "3",
          "orderNumber": 3,
          "typeEnum": "FormulaElement",
          "description": {
            "language": "de-DE",
            "text": "another formula element"
          },
          "formulaValues": [
            {
              "row": {
                "value": 6,
                "calculation": "8",
                "orderNumber": 1,
                "typeEnum": "FormulaValue"
              }
            }
          ]
        }
      }
    ]
  }
]

Remarks
When you use a formula in the structure of an time element, you have to inform you, about the structure of the formula element. Only with this information, you can override the formula parameters in the right way.

2.2 Update Time elements

To update a Time element with the TiCon4 REST API, you have to create a JSON structure in the request body and send it as a PATCH request. The JSON structure is as the same as discussed in chapter 2.1 It is necessary to know the Uid of the element you want to update.

Important: To change an element, all simple properties and dictionaries must be specified in the request body, regardless of whether their values have to be changed or not! Exceptions are navigation properties and properties of type LocaleText like description, begin, end.

Use the following call to patch a Time element:

{{ServerAddress}}/ticon-web/services/data/time-elements

2.2.1 Simple example

At first an example how to update the texts field of the Time element in the header view.

[
  {
    "code": "AN.1...3",
    "folderUid": "Folder-130",
    "ownerUid": "Account-2",
    "elementConfigurationUid": "ElementClassConfiguration-100013",
    "description": {
      "language": "en-US",
      "text": "change the description with TiCon4 REST API"
    },
    "begin": {
      "language": "en-US",
      "text": "change the starts with TiCon4 REST API"
    },
    "end": {
      "language": "en-US",
      "text": "change the ends with TiCon4 REST API"
    },
    "limit": {
      "language": "en-US",
      "text": "change limitations with TiCon4 REST API"
    },
    "content": {
      "language": "en-US",
      "text": "simple change example with TiCon4 REST API"
    },
    "uid": "Element-14719",
    "elementStatusUid": "ElementStatus-7",
    "elementTypeUid": "ElementType-1",
    "workorganizationType": "None"
  }
]

The table below lists where to find the data numbered in the TiCon screenshot.

No.	Content	Property Name and Remarks
1	Description of element	entity.description.text
2	Start of element	entity.begin.text
3	Includes of element	entity.content.text
4	Ends of element	entity.end.text
5	Limitations of element	entity.limit.text

2.2.2 Full example

At next a full patch example of a Time element. To change the structure of the Time element, you have to add a whole JSON structure with the original identifiers and do your changes inside (i.a. texts, indicator criterions). When you want to add a new row, don't add the property identifier, if you want to delete a row, don't mention this row, see example below.

[
  {
    "elementConfigurationUid": "ElementClassConfiguration-100013",
    "description": {
      "language": "en-US",
      "text": "change the description with TiCon4 REST API"
    },
    "begin": {
      "language": "en-US",
      "text": "change the starts with TiCon4 REST API"
    },
    "end": {
      "language": "en-US",
      "text": "change the ends with TiCon4 REST API"
    },
    "limit": {
      "language": "en-US",
      "text": "change limitations with TiCon4 REST API"
    },
    "content": {
      "language": "en-US",
      "text": "simple change example with TiCon4 REST API"
    },
    "code": "AN.1...4",
    "folderUid": "Folder-130",
    "ownerUid": "Account-2",
    "index": 1,
    "uid": "Element-14719",
    "times": {
      "ttbUser": 2500.665,
      "ttu": 3416.6666666666665,
      "ttuUser": 2300,
      "twUser": 2500,
      "tg": 3416.6666666666665,
      "te": 3416.6666666666665,
      "t": 3416.6666666666665
    },
    "elementTypeUid": "ElementType-2",
    "elementStatusUid": "ElementStatus-7",
    "workorganizationType": "None",
    "structure": [
      {
        "identifier": "173119",
        "row": {
          "elementUid": "Element-1005",
          "factor": "2.5",
          "ordernumber": 1,
          "typeEnum": "Element",
          "description": {
            "language": "en-US",
            "text": "Changed with TiCon4 REST API"
          },
          "criterionUids": [
            {
              "key": "1",
              "value": "IndicatorCriterion-10003"
            }
          ]
        }
      },
      {
        "identifier": "173120"
      },
      {
        "identifier": "173121"
      },
      {
        "identifier": "173122"
      },
      {
        "row": {
          "elementUid": "Element-13605",
          "factor": "1.0",
          "ordernumber": 5,
          "typeEnum": "Element",
          "description": {
            "language": "en-US",
            "text": "stoop for deep-drawing film condenser module"
          },
          "criterionUids": [
            {
              "key": "1",
              "value": "IndicatorCriterion-10003"
            }
          ]
        }
      }
    ]
  }
]

No.	Content	Property Name and Remarks
1	Cod of element	entity.code
2	Index of element	entity.index
3	Description of element	entity.description.text
4	Type of element	entity.elementTypeUid you need the Uid of element type, see chapter 6.6.5
5	Status of element	entity.elementStatusUid you need the Uid of element status, see chapter 6.6.6
6	Basic time of element	entity.times.tg
7	Start of element	entity.begin.text
8	Includes of element	entity.content.text
9	Ends of element	entity.end.text
10	Limitations of element	entity.limit.text

No.	Content	Property Name and Remarks
11	Description of used row element	entity.structure[].row.description.text
12	Factorstring of usage	entity.structure[].row.factor
13	Indicators	entity.structure[].row.criterionUids[].IndicatorCriterion you need the Uid of indicator criterion, see chapter 6.6.7
14	Order number of structure row	entity.structure[].row.orderNumer

Remarks
Please remember, all times have to be set in TMU.

2.3 Formula elements

The next chapter will describe how to create a new Formula element with the TiCon4 REST API. To create a new element, you have to create a JSON structure in the request body and send it as a POST request. Following properties are mandatory:

• Code
• folderUid
• ownerUid
• elementConfigurationUid
• calculation

To create a new Formula element with the TiCon4 REST API you have to call the following URL:

{{ServerAddress}}/ticon-web/services/data/formula-elements

2.3.1 Simple example

At first a very simple example, to create a Formula element with code and a certain element class configuration, the user needs the minimum permission write .

[
  {
    "code": "SIMPLE.FORMULA.EXAMPLE",
    "calculation": "PI * 3,043",
    "folderUid": "Folder-131",
    "ownerUid": "Account-2",
    "elementStatusUid": "ElementStatus-3",
    "elementTypeUid": "ElementType-1",
    "elementConfigurationUid": "ElementClassConfiguration-4501"
  }
]

2.3.2 Full example

Here a full example of a Formula element.

[
  {
    "code": "FULL.FORMEL.EXAMPLE",
    "calculation": "PI * 3,043",
    "folderUid": "Folder-131",
    "ownerUid": "Account-2",
    "formulaType": "Time",
    "timeType": "Ttu",
    "courseOfTimeType": "Separate",
    "elementStatusUid": "ElementStatus-3",
    "elementTypeUid": "ElementType-1",
    "elementConfigurationUid": "ElementClassConfiguration-4501",
    "description": {
      "language": "de-DE",
      "text": "Komplettes Formelbeispiel mit der Rest API"
    },
    "formulaCriterionUids": [
      {
        "key": "1",
        "value": "IndicatorCriterion-10003"
      }
    ],
    "structure": [
      {
        "row": {
          "variable": "L",
          "timeType": "Ttu",
          "parameterType": "Variable",
          "orderNumber": 1,
          "defaultInput": "2 * 1,0",
          "description": {
            "language": "de-DE",
            "text": "Variable L"
          }
        }
      },
      {
        "row": {
          "variable": "I",
          "timeType": "Ttu",
          "parameterType": "Variable",
          "orderNumber": 2,
          "min": 1,
          "max": 10,
          "description": {
            "language": "de-DE",
            "text": "Variable I"
          }
        }
      }
    ]
  }
]

Remarks
The defaultInput has a default value of 1 * 1.0 when the parameterType is Variable or Constant. The REST API calculates the default value automatically.

2.4 Update Formula elements

To update a Formula element with the TiCon4 REST API, you have to create a JSON structure in the request body and send it as a PATCH request. The JSON structure is as the same as discussed in chapter 2.3 It is necessary to know the Uid of the element you want to update.

Use the following call to patch a Formula element:

{{ServerAddress}}/ticon-web/services/data/formula-elements

2.4.1 Example

Here a full example, where you can see, how to update a Formula element.

[
  {
    "code": "FULL.FORMEL.EXAMPLE...CHANGED",
    "calculation": "PI * 14",
    "folderUid": "Folder-131",
    "ownerUid": "Account-2",
    "formulaType": "Time",
    "timeType": "Ttu",
    "courseOfTimeType": "Separate",
    "elementStatusUid": "ElementStatus-3",
    "elementTypeUid": "ElementType-1",
    "elementConfigurationUid": "ElementClassConfiguration-4501",
    "uid": "Element-13578",
    "description": {
      "language": "de-DE",
      "text": "Beispiel Text, geändert mit REST API"
    },
    "formulaCriterionUids": [
      {
        "key": "1",
        "value": "IndicatorCriterion-10002"
      }
    ],
    "structure": [
      {
        "row": {
          "variable": "L",
          "timeType": "Ttu",
          "parameterType": "Variable",
          "orderNumber": 1,
          "defaultInput": "4 * 1,5",
          "description": {
            "language": "de-DE",
            "text": "Beispiel Variable L"
          }
        },
        "identifier": "169832"
      },
      {
        "row": {
          "variable": "I",
          "timeType": "Ttu",
          "parameterType": "Variable",
          "orderNumber": 2,
          "min": 1,
          "max": 5
        },
        "identifier": "169833"
      }
    ]
  }
]

2.5 Reading and writing criteria

Criteria are used to store individual data on any element within TiCon. Criteria are created in the TiCon Admin. There you can define a code, to identify the criterion, and basic settings like a description, a type (text, number, date, …) and additional data. After that a criterion must be assigned to an element configuration.
Definition of criteria in TiCon Admin and assignment of criteria to element configurations in TiCon Admin.

Criteria can be used with any element type, such as time elements, formula elements, product work piece elements and so on.

The following examples demonstrate the usage with time elements. If you want to work with other types, you must use the corresponding end points and the json required for the element type. However, the criteria part will always be the same.

Display of criteria values in TiCon client.

The easiest way to start is to create an element within TiCon and afterwards query this element to see the required json.

With the following query you receive this json. It contains two criteria, a text criteria with the code DP and the value of “Test department” and a number criteria with the code ONR with the value of 42.

GET {{ServerAddress}}/ticon-web/services/data/time-elements?code=3000KA.....5&expand[criteria][row]

{
  "entities": [
    {
      "elementStatusUid": "ElementStatus-7",
      "elementTypeUid": "ElementType-1",
      "elementConfigurationUid": "ElementClassConfiguration-4104",
      "folderUid": "Folder-20",
      "criteria": [
        {
          "row": {
            "elementCriterionUid": "ElementCriterion-1006",
            "textValue": "Test department",
            "elementCriterionCode": "DP"
          },
          "identifier": "19323"
        },
        {
          "row": {
            "elementCriterionUid": "ElementCriterion-1044",
            "numberValue": 42,
            "elementCriterionCode": "ONR"
          },
          "identifier": "30186"
        }
      ],
      "code": "3000KA.....5",
      "objectType": "TimeElement",
      "uid": "Element-259"
    }
  ],
  "expanded": []
}

You can read the criterion''s code in the property elementCriterionCode and the Uid in the property elementCriterionUid. The value is stored depending on the type of the criterion in the properties:

• numberValue for numeric and boolean criteria
• textValue for alpha numeric and date criteria
• fixedCriterionValueCode and fixedCriterionValueUid for criteria with value lists
• If there is none of these fields the value of the criterion is null.

To create an element with a criteria value you can recycle the json received with the GET request. If you want to create an element with the same criteria value as in the above example you may use the following json.

POST {{ServerAddress}}/ticon-web/services/data/time-elements?lang=en-US

[
  {
    "workOrganizationType": "BreaksEveryTime",
    "elementStatusUid": "ElementStatus-3",
    "elementTypeUid": "ElementType-1",
    "elementConfigurationUid": "ElementClassConfiguration-4101",
    "folderUid": "Folder-10",
    "criteria": [
      {
        "row": {
          "elementCriterionUid": "ElementCriterion-1006",
          "textValue": "Test department",
          "language": "en-US"
        }
      },
      {
        "row": {
          "elementCriterionUid": "ElementCriterion-1044",
          "numberValue": 42,
          "language": "en-US"
        }
      }
    ],
    "code": "MY-DEMO-ELEMENT",
    "objectType": "TimeElement"
  }
]

To update the criteria on existing elements you can use the following json. You have to input the element uid of the element you want to change and the criterion uid of the criterion you want to change. If you like you can change the value of multiple criteria by sending more rows. Unspecified criteria will not be changed.

PATCH {{ServerAddress}}/ticon-web/services/data/time-elements?lang=en-US

[
  {
    "criteria": [
      {
        "row": {
          "elementCriterionUid": "ElementCriterion-1006",
          "textValue": "Changed Department",
          "language": "en-US"
        }
      }
    ],
    "uid": "Element-14250"
  }
]

3 Data structure in TiCon

In TiCon we distinguish between Administration Data and Element Data. Element Data refers to all elements stored within TiCon, that the TiCon user regularly works with. These elements can be Time Elements, also known as analyses or Balancing elements, and others. Time Elements are built by the composition of other Time Elements, like MTM basic time elements as the UAS elements KA, AA1 etc.

Each element has some basic data like a folder where a code, index, variant, and description are stored, and even more. Folder, code, index, and variant form a natural unique key. Furthermore, there is an artificial unique key to identify elements.

Each type of element - we call them element class - has additional unique properties. Besides the element class, which identifies the type of the element there is a so-called element configuration that controls what data is visible to the user and how the element can be composed from others, as well as, user rights that are given to the different configurations.

4 Concepts of the API

4.1 Design philosophy - General design decisions

4.1.1 Orthogonality

The CRUD operations with entities are orthogonal. That is: the REST endpoints are different, but the same parameters in the same format can be used for all these REST endpoints. Also, the JSON formats in request and response are the same, apart from the entity's different object type in each case.

The advantage of orthogonal APIs is that they are easier to use, because the parameter set and the request/response object only need to be understood once and can then be applied to all endpoints.

4.1.2 Idempotency

The CRUD operations GET and PATCH with entities are idempotent. That is, the same REST call with the same parameters produces the same state on the server and returns the same response.

Multiple identical GETs return the same response and do not change the state on the server, so the operation is idempotent. Multiple identical PATCHes change the state on the server, but in an identical way, and return the same response. The operation is therefore idempotent.

A POST creates multiple entities with different UIDs when called multiple times. The operation is therefore not idempotent.

A DELETE returns an error on the second call, since the resource with the specified UID is then no longer available. The operation is therefore also not idempotent.

4.1.3 GET-by-URL

Reading operation with the GET verb hold all the parameters entirely in the URL (except authorization data if basic authorization is used).

That is: a GET call for entities can be reproduced by simply copying the URL. There is no "hidden" parameter part in the header.

4.1.4 No OData

The API is not OData compliant because it doesn't add any value to the supported use cases, and would increase complexity and implementation effort as well as limiting the API's flexibility.

4.1.5 Extensibility and backward compatibility

The API will be kept backward compatible in recent subsequent versions so that older clients can work with servers that use newer API versions.

This imposes the following constraints for API extensions:

• new endpoints with new parameters and new data models may always be introduced
• existing endpoints will be kept backward compatible, i.e:
  • new parameters may be added, but they will be optional, because old clients do not use these parameters, and the default case (i.e., without specifying the parameter) will behave the same as the old version of the API
  • existing parameters (and data models) may be extended by new properties, but these properties will also be optional, and the default case will again behave like in the old version of the API (see above)
  • GET may provide more complex data models than in the old API, the old client should ignore the additional properties.

To obtain the current version number you may call {{ServerAddress}}/ticon-web/services/management/version (GET).

4.1.6 High-level API and dumb clients

The TiConWeb API is supposed to be a high-level API. This means fewer, but more large-scale server requests. An API operation combines more functionality in itself, so it has a higher level of abstraction.

Examples

• Create time elements with structure and time vector in one POST request instead of creating time vector and structure first by several single requests.
• Request rendered data card from server instead of requesting all needed information by 100 single requests, in order to render it on the client.

This has the following advantages

1. Better performance, especially shorter response time for users.
2. The server has to trust the client less, which is very important, especially in the cloud environment. The correct flow control is ensured on the server side. A client can also not maliciously cause damage if it takes over the flow control itself, e.g. through:
   • Connection failures or browser crashes while the client is in the middle of a flow (e.g., creating or deleting a time block)
   • Implementation errors in the client
3. Easier usability of the API, better implementability of the client. Client needs less concrete knowledge about data models, flow control and business logic (Dumb Client). These are encapsulated as implementation details on the server side.
4. Better flexibility / extensibility of the API. Due to fewer adjustments required to the client in case of changes to the API.

4.1.7 Data multilingualism and translations

The TiConWeb API supports data multilingualism. However, in the CRUD operations with entities, only one language is transmitted. This corresponds to the workflow of the functional modification of a text, which is done with the language of the current user.

For translation, there are dedicated endpoints that allow reading / writing of all translations for each property.

4.2 CRUD operations with entities

4.2.1 Entities versus Models

We distinguish two types of data in the API:

• Entities - objects than can live on their own with their own UId in the database. For each entity type there is a separate REST endpoint to perform CRUD operations with the corresponding entities.
• Models - objects that are also persisted in the database, but are used only as a substructure of exactly one entity.

Examples of models are the time vector and structure lines in time elements. Whereas an example of an entity is a time element, and indicator criteria as it is used not only within indicator categories, but also from time elements and structure lines.

Models differ from entities on the data side in the following ways:

1. From a database perspective, a Model can be a standalone Entity - with its own Id or UId - but it does not have to be. This is an implementation detail of the backend, and from a REST perspective is abstracted away.
2. Models (from REST point of view) don't have UIds either, because not every backend has UIds for models
3. Models do not have their own REST endpoints either. Only entities have REST endpoints

4.2.2 IDs versus UIDs

From a REST perspective, entities always have a UId. UIds and Ids are not the same thing:

• UId - identifies the object globally, regardless of the object type.
• Id - identifies the object within a type or type hierarchy (source table). Only the tuple (Id, origin table) therefore identifies the object globally.

For example, in the TiCon4 database a folder can have Id 42 and a time element can have Id 42. However, two time elements can not share the same Id, as they are stored in the same table.

In the API the UId is always constructed by the object name and it's Id, e. g.: Folder-20.

5. Authorization

This API uses the Basic Authentication scheme. In context of an HTTP transaction, basic access authentication is a method for an HTTP user agent to provide a username and password when making a request. Every request contains a header field in the form of Authorization: Basic <credentials>, username and password splitted by a single colon.

The credentials are built by the TiCon username and the corresponding password. A REST endpoint will only provide the data the corresponding TiCon user would be able to see. Writing (creating, updating, and deleting) is handled in the same way.

6 Entity GET

6.1 structure and behavior

The generic endpoint for reading entities of type Foo has two flavors:

• GET /foo/{uid}<L><E> - returns exactly one entity with UId uid, and throws a 4xx error, if the entity could not be loaded. Possible error reasons are:
  • no entity with the specified UId was found (404)
  • UId is present but the entity is not of type Foo (404)
  • User does not have access authorization (403)
  • Other (400)
• GET /foo<F><P><L><E> - returns a list of entities that match the specified filter <F> and are within the specified paging range.
  • No 4xx errors are returned if one of the specified UIds does not exist or the user does not have access on an element, but the resource is simply not found by the filter.

This behavior is consistent because when called in the first variant, e.g. /time-elements/Element-259, the parameter has the logic of a path to a resource and the path does not exist or is inaccessible. In the second variant, e.g. /time-elements?uids=Element-259, the path is accessible (/time-elements), and uids=42 has the logic of a search filter. Therefore, no 4xx error should be returned here.

In both variants, the endpoint returns an error if the client-side call was correct, but an error occurred on the server (5xx).

6.2 Filter parameters <F>

Specification of the filter is optional. If no filter is specified, all entities of the respective type will be returned limited only by paging.

The following filter parameter can be used for each entity type:

• uids - filter by one or more uids.

Other possible filters depend on the specific entity type. For time elements, for example, there are the filters code (for the element's code) and user (owner of the element).
If you want to know, how much elements counts the total result, you can add a total counter at the end of JSON result by set counttotalresults=true in your query.

Examples

• uids=Element-259,Element-258 - Search for items with UIds Element-259 and Element-258
• code=*AA1* - Search for elements whose code contains AA1
• code=TEST*&user=mtm - Search for items whose code starts with TEST and is owned by user mtm.
• description=*time* - Search for elements whose description contain time

6.3 Paging parameter <P>

The page size can be given as a query parameter for each endpoint able to return more than one entity.

• pageSize - maximum number of results to return, even if the filter matches more items. Used in combination with pageOffset as the page size for paging.
• pageOffset - number of elements to be skipped.

When paging is used the items have to be sorted by sortBy parameter.

Examples

• pageSize=50 - search limited to 50 results, no defined order
• pageSize=50&pageOffset=150&sortBy=uid - skip the first 150 elements, page size is 50 elements and ordered by UID

Remarks
You can configure the pageSize in the app settings, you have to set the property MaxPageSize. When no configuration is found, the default value is 100, the max value is 10000!

6.4 Language parameter <L>

Optional specification of the data language for language texts from the database. If the parameter is not specified or a property is not available in one of the requested languages, the property is returned in its source language.

Examples

• lang=de-DE,en-US - Returns texts in German if they are in German, otherwise in English, otherwise in their original data language.
• lang=fr - Returns texts in French if they are in French, otherwise in their original data language.

6.5 Expand parameter <E>

When data is requested the REST API only returns data stored in primitive data types (like numbers or strings). If you require complex data and multilingual data you have to request it by using property expansion.

A distinction is made between different property types, for which different expansion rules apply:

• Primitive properties are always loaded. This cannot be turned on or off by expansion policy.
  • Primitive properties are identified by the type (like string, number, boolean, enumeration, ...)
• Model-Object and Arrays properties are not loaded by default.
  • Loaded means: the model object is also transferred in the response object, with direct JSON inlining at the property.
  • Not loaded means: the property is completely omitted and not contained in the JSON.
  • Model-Object properties can be expanded in the schema view from the OpenAPI documentation. They can be distinguished from _Entity_s by the lack of a UID.
• Language Text properties are not loaded by default. Loading must be explicitly specified in the expansion policy for the property in question.
  • Loaded means: the text including meta data is also transferred in the response object, with direct JSON inlining at the property.
  • Not loaded means: the property is set to null.
  • That are complex types composed by a language, text and isSource property.
• Entity properties are not loaded by default. Loading must be explicitly specified in the expansion policy for the property in question.
  • Loaded means: the model object is also transferred in the response object, but there is no direct JSON inlining on the property. Instead, the entity's UID is passed as the property value, and the entity itself is appended to a list (expanded) in the response object. It is handled in this way because an entity - in contrast to model objects - can be referenced several times in the response. Thus this approach saves bandwidth. Furthermore, there is no guarantee that entity graphs are free from cycles.
  • Not loaded means: the UID of the referenced entity is specified as the value for the property (not null as with model objects), but the entity is not appended to expanded in the response object.
  • These properties end with Uid or Uids

From the OpenAPI documentation it is easy to determine which properties need expansion to retrieve their values, because every time you can expand a property in the schema view it also needs expansion for data retrieval (except for enums, which can be expanded in the documentation's schema view, but are always loaded as they are primitive data types).

Examples

expand[description]

The above expansion query parameter will retrieve the description of an entity. The description is a Language Text property and as such not expanded by default. You'll find the value directly in the JSON, like this

{
  "description": {
    "language": "en-US",
    "text": "Walk / m",
    "isSource": true
  }
}

expand[folder]

The above expansion query parameter will retrieve the folder entity. The expanded folder object can be found in the expanded section by searching for the uid. The expanded object cannot be found directly in the property because a folder is a separate entity.

{
  "entities": [
    {
      "folderUid": "Folder-20"
    }
  ],
  "expanded": [
    {
      "code": "MTM-UAS-BASE",
      "objectType": "Folder",
      "uid": "Folder-20"
    }
  ]
}

expand[folder][description] - A property expansion can be nested as in the preceding example where the description of folder entities is expanded. This will implicitly expand the folder as well.

expand[description] - load the description of an element (directly in the entity as the description is a model property)

expand[structure][row][element][description] - load the used structure element in the expand section as the used element is a separate entity. The used element's description will also be loaded and can be found in the used element itself.

expand[workorganization] - loads the workorganization properties of the element.

{
  "workorganization": {
    "grossShiftDuration": 850000,
    "netShiftDuration": 800000,
    "taktDuration": 0,
    "piecesPerShift": 0,
    "performance": null,
    "totalAllowance": null,
    "availableTgPerShift": 800000,
    "additionalTimePersonal": null,
    "additionalTimeObjective": null,
    "nonRepetitiveDifferenceDuration": 800000,
    "nonRepetitiveDuration": 0,
    "inputModeType": "NetWorkingTimeAndTaktTime",
    "workplaceSizeType": "SmallWorkplace",
    "bodyPercentile": 50,
    "genderType": "None"
  }
}

expand[timetgbycriterionuid] - loads the time TG by criterion structure of the element.

{
  "timeTgByCriterionUid": [
    {
      "key": "IndicatorCriterion-3",
      "value": 0
    },
    {
      "key": "IndicatorCriterion-10001",
      "value": 0
    },
    {
      "key": "IndicatorCriterion-10004",
      "value": 0
    },
    {
      "key": "IndicatorCriterion-1",
      "value": 0
    },
    {
      "key": "IndicatorCriterion-10000",
      "value": 0
    },
    {
      "key": "IndicatorCriterion-10005",
      "value": 0
    },
    {
      "key": "IndicatorCriterion-10002",
      "value": 0
    },
    {
      "key": "IndicatorCriterion-2",
      "value": 0
    },
    {
      "key": "IndicatorCriterion-10003",
      "value": 0
    }
  ]
}

expand[workorganizationBreakStructure][row][description] - loads the used workorganization break structure element in the expand section as the used element is as separate entity.

{
  "workorganizationBreakStructure": [
    {
      "identifier": "766",
      "row": {
        "duration": 50000,
        "description": {
          "language": "de-DE",
          "text": "Mittagspause",
          "isSource": true
        }
      }
    },
    {
      "identifier": "767",
      "row": {
        "duration": 50000,
        "description": {
          "language": "de-DE",
          "text": "Erholpause",
          "isSource": true
        }
      }
    }
  ]
}

expand[structure][row][times] - loads the times of the used time element or the sum of all times in section for all rows.

{
  "row": {
    "times": {
      "ttu": 27.777777777777775,
      "tg": 27.777777777777775,
      "te": 27.777777777777775
    }
  }
}

expand[structure][row][totalTimes] - loads the times with mulitplicated factor (all factors inclusive additional factor).

{
  "row": {
    "totalTimes": {
      "tg": 69.44444444444444,
      "te": 69.44444444444444
    }
  }
}

6.5.1 NULL value handling

The default NULL value handling is, that properties, without a valid number, enum or string, are not available in JSON result. The reason is for this behavior is, to make the HTTP stream smaller, especially with very complex classes, such as the time vector or a very complex structure.

Is zero printed or not?
In all TiCon classes, zero values are displayed in JSON structure, because in the most cases, they are relavant informations. An exception is the time vector class. They is very complex and has a large number of properties, that can become confusing very quickly. For this reason, all times that are zero are not displayed in JSON result, only times that are not zero.

At the moment there is a special exception regarding the NULL value handling. This is the query of folders, if there is no parent directory, an empty string is displayed in the JSON result. This should be changed in the future and adapted to the standard NULL value handling.

6.6 Examples

6.6.1 Time Elements

Here you will find some examples for getting time elements by using the endpoint {{ServerAddress}}/ticon-web/services/data/time-elements

Basic parameters

• code filters elements by a certain CODE parameter.
  
• uids filters elements by UIDs, separated by comma.
  
• codewildcards true to use wildcards in element search
  
• pagesize the maximum number of shown elements. The default value is 20 and the max number of elements is limited to 100!
  
• expand true to get details about complex navigation properties, like a structure, row. If a property can be extended via expand, it can be seen from the UID extension in the property name, see elementStatusUid or analyzeMethodUid at the return example below. All expanded properties can be found in the expanded clause at the end of the JSON string.

Returns

A list of all elements from all folders except the DataCard folder, where the current user has the minimum permission read.

{
  "entities": [
    {
      "shortCode": "AHG02",
      "analyzeMethodUid": "AnalyzeMethod-3",
      "times": {
        "ttbUser": 16,
        "tg": 16,
        "te": 16,
        "t": 16
      },
      "defaultCriterionUids": [
        {
          "key": "0",
          "value": "IndicatorCriterion-1"
        },
        {
          "key": "1",
          "value": "IndicatorCriterion-2"
        },
        {
          "key": "2",
          "value": "IndicatorCriterion-3"
        }
      ],
      "timeTgByCriterionUid": [
        {
          "key": "IndicatorCriterion-2",
          "value": 0
        },
        {
          "key": "IndicatorCriterion-3",
          "value": 0
        },
        {
          "key": "IndicatorCriterion-10001",
          "value": 0
        },
        {
          "key": "IndicatorCriterion-10004",
          "value": 0
        },
        {
          "key": "IndicatorCriterion-10002",
          "value": 0
        },
        {
          "key": "IndicatorCriterion-1",
          "value": 0
        },
        {
          "key": "IndicatorCriterion-10003",
          "value": 0
        },
        {
          "key": "IndicatorCriterion-10005",
          "value": 0
        },
        {
          "key": "IndicatorCriterion-10000",
          "value": 0
        }
      ],
      "createTime": "1983-08-28T00:00:00",
      "modifyTime": "1997-10-28T00:00:00",
      "ownerUid": "Account-2",
      "modifyUserUid": "Account-2",
      "elementStatusUid": "ElementStatus-7",
      "elementTypeUid": "ElementType-1",
      "elementConfigurationUid": "ElementClassConfiguration-4104",
      "folderUid": "Folder-19",
      "code": "2000AHG02..4",
      "objectType": "TimeElement",
      "uid": "Element-10"
    }
  ],
  "expanded": [
    {
      "categoryUid": "IndicatorCategory-2",
      "color": "FFFFFF",
      "code": "NONE",
      "objectType": "ProcessIndicatorCriterion",
      "uid": "IndicatorCriterion-2"
    },
    {
      "categoryUid": "IndicatorCategory-3",
      "color": "FFFFFF",
      "code": "NONE",
      "objectType": "ProcessIndicatorCriterion",
      "uid": "IndicatorCriterion-3"
    },
    {
      "categoryUid": "IndicatorCategory-1",
      "color": "FFFFFF",
      "code": "NONE",
      "objectType": "ProcessIndicatorCriterion",
      "uid": "IndicatorCriterion-1"
    }
  ]
}

Examples
The following examples demonstrate how to find time elements by code or UIDs, how to use wild card search and expand structure and description.

{{ServerAddress}}/ticon-web/services/data/time-elements?code=3000AA1....5
{{ServerAddress}}/ticon-web/services/data/time-elements?uids={{uid}},{{uid}}
{{ServerAddress}}/ticon-web/services/data/time-elements?code=AN*&codewildcards=true
{{ServerAddress}}/ticon-web/services/data/time-elements?code=AN*&codewildcards=true&pagesize=5
{{ServerAddress}}/ticon-web/services/data/time-elements/Element-13?expand[defaultcriterion]=true&counttotalresults=true
{{ServerAddress}}/ticon-web/services/data/time-elements?code=AN*&codewildcards=true&expand[description]&expand[structure][row][element][description][elementconfiguration]&expand[times]
{{ServerAddress}}/ticon-web/services/data/time-elements?code=B.13744&expand[description]&expand[structure][row][element][description]&expand[structure][row][criterion][description]&expand[defaultcriterion][description]
{{ServerAddress}}/ticon-web/services/data/time-elements?expand[structure][row][criterion][description]&expand[structure][row][element][times]&expand[timetgbycriterionuid]&expand[times]&code=An.1...4&expand[structure][row][singletime]&expand[structure][row][totalTime]&expand[workOrganization]&expand[times]
{{ServerAddress}}/ticon-web/services/data/time-elements?expand[description]=&expand[criteria][row]&expand[criteria][row][fixedCriterionValue][description]&expand[criteria][row][elementCriterion][description]

Here is another example, how to get formula values in a time element.

{{ServerAddress}}/ticon-web/services/data/time-elements?expand[structure][row]&code=xxxx&expand[structure][row][description]&expand[structure][row][element]&expand[structure][row][formulavalues][row]

As you can see, it's always the same principle, when you want to get extended properties, expand it! Please take a look here.

Remarks
All text properties, as description, begin, end and can also be expanded, but the properties are displayed directly on the property in the JSON string and not in the expanded node, as described above. Other exceptions are: structure, element, row depending on which element type is queried.

6.6.2 Stream Elements

{{ServerAddress}}/ticon-web/services/data/stream-elements?expand[structure]

The most import property is the structure property, that is constructed as follows:

• Contains an entry for each
  • variant (typeEnum = Stream2Variant)
  • station (typeEnum = Stream2Station)
  • worker/machine (typeEnum = Stream2Resource)
  • allocation to a worker (typeEnum = Stream2Allocation)
  • other data, such as content from the work content and more
• There is always at least one line of type Stream2Variant
• Structure is tree-like, the parent-child relationships can be interfered from the order (sorted by order number)
  • Variants have no parent
  • The station's parent is the variant with the largest ordinal number that is smaller than that of the station
  • The parent of a worker/machine is the station with the largest ordinal number that is smaller than that of the worker/machine
  • The parent of an allocation is the worker/machine with the largest ordinal number that is smaller than that of the allocation

Examples

{{ServerAddress}}/ticon-web/services/data/stream-elements
{{ServerAddress}}/ticon-web/services/data/stream-elements?code=T861600&expand[owner]&expand[elementConfiguration][description]&expand[folder][description]&expand[folder][parentFolder][description]
{{ServerAddress}}/ticon-web/services/data/stream-elements?code=T861600&expand[description]&expand[elementType][description]&expand[elementStatus][description]&expand[structure][row][description]
{{ServerAddress}}/ticon-web/services/data/stream-elements?code=T861600&expand[description]&expand[elementType][description]&expand[workorganizationBreakStructure][row][description]
{{ServerAddress}}/ticon-web/services/data/stream-elements?expand[description]&expand[workorganizationBreakStructure][row][description]&expand[workorganization]

6.6.2.1 Stream Elements times

The time section is a very important value of the structure property in Stream elements. It exists the following time properties:

• entity.structure[].row.times
• entity.structure[].row.ergoTimes

Examples

{{ServerAddress}}/ticon-web/services/data/stream-elements?expand[structure][row][description]&code=TZ733MH...Ü5&expand[description]&expand[structure][row][ergotimes]&expand[structure][row][criterionuids]
{{ServerAddress}}/ticon-web/services/data/stream-elements?expand[structure][row][description]&code=TZ733MH...Ü5&expand[structure][row][times]&expand[description]
{{ServerAddress}}/ticon-web/services/data/stream-elements?expand[workorganization]&expand[structure][row][description]&expand[structure][row][times]&expand[description]&folderuids=Folder-56

6.6.3 Folders

{{ServerAddress}}/ticon-web/services/data/folders

Returns a list of all folders, where the current user has the minimum permission read.

Examples

{{ServerAddress}}/ticon-web/services/data/folders?code=MTM&expand[description]&expand[parentFolder]
{{ServerAddress}}/ticon-web/services/data/folders?uids=Folder-1,Folder-10
{{ServerAddress}}/ticon-web/services/data/folders?code=MT*&codeWildcards=true
{{ServerAddress}}/ticon-web/services/data/folders?expand[description]&expand[parentfolder][description]&description=*prozessbau*&descriptionWildcards=true

To create a folder send a POST request to {{ServerAddress}}/ticon-web/services/data/folders with a body

[
  {
    "code": "NEU",
    "description": {
      "language": "de-DE",
      "text": "Neuer Ordner"
    },
    "type": "System",
    "parentFolderUid": "Folder-164"
  }
]

To delete a folder send a DELETE request to {{ServerAddress}}/ticon-web/services/data/folders/Folder-175

6.6.4 Element configurations

{{ServerAddress}}/ticon-web/services/data/element-configurations

To get all Element configurations from REST, where the current user has the minimum permission read.

Examples

{{ServerAddress}}/ticon-web/services/data/element-configurations?expand[description]
{{ServerAddress}}/ticon-web/services/data/element-configurations?uids={{uid}},{{uid}}
{{ServerAddress}}/ticon-web/services/data/element-configurations?expand[description]&description=*time*&descriptionWildcards=true

6.6.5 Element types

{{ServerAddress}}/ticon-web/services/data/element-types

Get all Element types from REST.

Examples

{{ServerAddress}}/ticon-web/services/data/element-types?expand[description]
{{ServerAddress}}/ticon-web/services/data/element-types?uids={{uid}}

6.6.6 Element statuses

{{ServerAddress}}/ticon-web/services/data/element-statuses

Get all Element status from REST.

Examples

{{ServerAddress}}/ticon-web/services/data/element-statuses?expand[description]
{{ServerAddress}}/ticon-web/services/data/element-statuses?uids={{uid}},{{uid}}

6.6.7 Indicator criterions

{{ServerAddress}}/ticon-web/services/data/process-indicators

Get all available indicator criterions from REST.

Examples

{{ServerAddress}}/ticon-web/services/data/process-indicators?expand[description]
{{ServerAddress}}/ticon-web/services/data/process-indicators?uids={{uid}},{{uid}}

6.6.8 Formula elements

{{ServerAddress}}/ticon-web/services/data/formula-elements

Get all Formula elements from REST.

Examples

{{ServerAddress}}/ticon-web/services/data/formula-elements?expand[description]&code=A..ZBAHS.TE5
{{ServerAddress}}/ticon-web/services/data/formula-elements?expand[description]&uids={{uid}},{{uid}}
{{ServerAddress}}/ticon-web/services/data/formula-elements?expand[description]&expand[structure][row][description]
{{ServerAddress}}/ticon-web/services/data/formula-elements?expand[formulacriterion][description]&expand[description]&expand[structure][row][description]&expand[structure][row][variableValues]
{{ServerAddress}}/ticon-web/services/data/formula-elements?expand[content]&expand[description]&index=idx&expand[longText1]&expand[images][row][element][binary]
{{ServerAddress}}/ticon-web/services/data/formula-elements?expand[content]&expand[description]&index=idx&expand[journal][row][journalDetails][row]
{{ServerAddress}}/ticon-web/services/data/formula-elements?expand[content]&expand[formulacriterion]&expand[structure][row][element]&expand[description]&expand[structure][row][description]&index=idx&expand[structure][row][variableValues][row][description]

6.6.9 Station elements

{{ServerAddress}}/ticon-web/services/data/resource-station-elements

Get all Station elements from REST.

No.	Content	Property Name and Remarks
1	Color	entity.color

Examples

{{ServerAddress}}/ticon-web/services/data/resource-station-elements?expand[description]&code=STATION
{{ServerAddress}}/ticon-web/services/data/resource-station-elements?expand[description]&uids={{uid}},{{uid}}
{{ServerAddress}}/ticon-web/services/data/resource-station-elements?expand[description]&expand[machinesOrOperators][row][description]
{{ServerAddress}}/ticon-web/services/data/resource-station-elements?expand[description]&expand[machinesOrOperators][row][description]&expand[carriers][row][description]&expand[tools][row][description]

6.6.10 Operator elements

{{ServerAddress}}/ticon-web/services/data/resource-operator-elements

Get all Operator elements from REST.

No.	Content	Property Name and Remarks
1	Color	entity.color

Examples

{{ServerAddress}}/ticon-web/services/data/resource-operator-elements?expand[description]&code=OPERATOR
{{ServerAddress}}/ticon-web/services/data/resource-operator-elements?expand[description]&uids={{uid}},{{uid}}
{{ServerAddress}}/ticon-web/services/data/resource-operator-elements?expand[description]&expand[qualifications][row][description]

6.6.11 Machine elements

{{ServerAddress}}/ticon-web/services/data/resource-machine-elements

Get all Machine elements from REST.

No.	Content	Property Name and Remarks
1	Color	entity.color

Examples

{{ServerAddress}}/ticon-web/services/data/resource-machine-elements?expand[description]&code=MACHINE
{{ServerAddress}}/ticon-web/services/data/resource-machine-elements?expand[description]&uids={{uid}},{{uid}}
{{ServerAddress}}/ticon-web/services/data/resource-machine-elements?expand[description]&expand[qualifications][row][description]
{{ServerAddress}}/ticon-web/services/data/resource-machine-elements?expand[description]&expand[qualifications][row][description]&expand[tools][row][description]

6.6.12 Carrier elements

{{ServerAddress}}/ticon-web/services/data/resource-carrier-elements

Get all Carrier elements from REST.

No.	Content	Property Name and Remarks
1	Color	entity.color

Examples

{{ServerAddress}}/ticon-web/services/data/resource-carrier-elements?expand[description]&code=CARRIER
{{ServerAddress}}/ticon-web/services/data/resource-carrier-elements?expand[description]&uids={{uid}},{{uid}}

6.6.13 Qualification elements

{{ServerAddress}}/ticon-web/services/data/resource-qualification-elements

Get all Qualification elements from REST.

No.	Content	Property Name and Remarks
1	Color	entity.color

Examples

{{ServerAddress}}/ticon-web/services/data/resource-qualification-elements?expand[description]&code=QUALIFICATION
{{ServerAddress}}/ticon-web/services/data/resource-qualification-elements?expand[description]&uids={{uid}},{{uid}}

6.6.14 Tool elements

{{ServerAddress}}/ticon-web/services/data/resource-tool-elements

Get all Tool elements from REST.

No.	Content	Property Name and Remarks
1	Color	entity.color

Examples

{{ServerAddress}}/ticon-web/services/data/resource-tool-elements?expand[description]&code=TOOL
{{ServerAddress}}/ticon-web/services/data/resource-tool-elements?expand[description]&uids={{uid}},{{uid}}

6.6.15 Material elements

{{ServerAddress}}/ticon-web/services/data/product-material-elements

Get all Material elements from REST.

No.	Content	Property Name and Remarks
1	Unit	entity.unit
2	Color	entity.color
3	Quantity	entity.quantity

Examples

{{ServerAddress}}/ticon-web/services/data/product-material-elements?expand[description]&code=MATERIAL
{{ServerAddress}}/ticon-web/services/data/product-material-elements?expand[description]&uids={{uid}},{{uid}}

6.6.16 ConsumableSupplies elements

{{ServerAddress}}/ticon-web/services/data/product-consumable-supplies-elements

Get all ConsumableSupplies elements from REST.

No.	Content	Property Name and Remarks
1	Unit	entity.unit
2	Color	entity.color
3	Quantity	entity.quantity

Examples

{{ServerAddress}}/ticon-web/services/data/product-consumable-supplies-elements?expand[description]&code=CONSUMABLESUPPLIES
{{ServerAddress}}/ticon-web/services/data/product-consumable-supplies-elements?expand[description]&uids={{uid}},{{uid}}

6.6.17 WorkPiece elements

{{ServerAddress}}/ticon-web/services/data/product-work-piece-elements

Get all WorkPiece elements from REST.

No.	Content	Property Name and Remarks
1	Unit	entity.unit
2	Color	entity.color
3	Quantity	entity.quantity

Examples

{{ServerAddress}}/ticon-web/services/data/product-work-piece-elements?expand[description]&code=WORKPIECE
{{ServerAddress}}/ticon-web/services/data/product-work-piece-elements?expand[description]&uids={{uid}},{{uid}}
{{ServerAddress}}/ticon-web/services/data/product-work-piece-elements?expand[description]&expand[bomUnitList][row][description]

6.6.18 Document elements

{{ServerAddress}}/ticon-web/services/data/document-elements

Get all Document elements from REST.

No.	Content	Property Name and Remarks
1	Source of binary data	entity.sourceType (either Database, Filesystem or Url)
2	Filesystem path	entity.path (if stored in Filesystem)
3	Time of creation of document data	entity.creationTimestamp
4	Size of document data	entity.size
5	Language of document	entity.language (see 6.4.)

Examples

{{ServerAddress}}/ticon-web/services/data/document-elements?expand[description]&code=DOCUMENT
{{ServerAddress}}/ticon-web/services/data/document-elements?expand[description]&uids={{uid}},{{uid}}

6.6.18.1 Document element binary data

If the document is stored inside the database (entity.SourceType equals Database) binary data can be extracted by expanding the binary section.

Examples

{{ServerAddress}}/ticon-web/services/data/document-elements?expand[description]&expand[binary]

6.6.19 AccountRoles

{{ServerAddress}}/ticon-web/services/data/accountRoles

Get all Roles from REST.

No.	Content	Property Name and Remarks
1	Category 1	entity.category1
2	Category 2	entity.category2
3	Category 3	entity.category3
4	Accounts	entity.accountRoles
5	Functions	entity.roleAdminObjects

Examples

{{ServerAddress}}/ticon-web/services/data/accountRoles?expand[description]&expand[category1]&expand[accountroles][account]
{{ServerAddress}}/ticon-web/services/data/accountRoles?expand[description]&expand[category1]&expand[accountroles]&expand[roleAdminObjects]

7 Entity Delete

To delete elements, you have to send the request as DELETE method.

{{ServerAddress}}/ticon-web/services/data/time-elements?elementuids=

Deletes elements by UIDs, when the current user has the minimum permission write.

Examples

{{ServerAddress}}/ticon-web/services/data/time-elements?elementuids={{uid}}
{{ServerAddress}}/ticon-web/services/data/time-elements?elementuids={{udi}},{{uid}}

Remarks
The Microsoft IIS server don't allow the delete method by default. Don't forgive to enable this feature in your side settings, bevore use the delete possibility of the REST API.

8 Entity Duplicate

To duplicate elements, you have to create duplicate information as JSON in the request body and send it as POST to the server.

{{ServerAddress}}/ticon-web/services/data/duplicate

Examples

{
  "isDuplicateChildren": true,
  "isRemoveDocumentElements": false,
  "isRemoveAssignmentElements": false,
  "isRemoveCycleInformation": false,
  "isResetTexts": false,
  "elements": [
    {
      "uid": "Element-14172",
      "newCode": "P1-X",
      "newIndex": "I1",
      "newVariant": "V1",
      "newFolderUid": "Folder-136"
    },
    {
      "uid": "Element-14173",
      "newCode": "P2-X",
      "isChild": true
    }
  ]
}