Configuration Details

Overview

This extension enables REST-based integration between SmarTeam and SAP S/4HANA through the TIF Cloud platform.

SmarTeam interacts with TIF by invoking REST endpoints. Each request triggers a configured TIF job, which:

Receives the source data from the request payload
Processes, maps, and enriches the data
Creates the SAP S/4HANA payload required for the target operation
Sends the generated SAP payload to SAP S/4HANA

All services are exposed via:

POST {tif-base-url}/integration/api/v1/newjob/smarteam/<rest-mapping>

Most endpoints expect the request body to be a single JSON object. Send Document supports either:

application/zip with a payload.json file and one document file inside the ZIP
application/json for URL-based document references

Fields marked with callouts (e.g., 1, 2, …) are mandatory unless specified otherwise.

REST Endpoints

Each endpoint represents a specific business operation and triggers a corresponding TIF job.

The following REST mappings are included:

Send Material

REST Mapping : /material

{
  "Product": "<name>", (1)
  "ProductDesc": "<description>", (2)
  "MaterialRevisionLevel": "<revision level>",
  "ProductType": "<Prodtype eg: FERT or ROH>",
  "Plant": "<plant number>",
  "NetWeight": "<weight>",
  "WeightUnit": "<weight unit>",
  "BaseUnit": "unit",
  "ProductGroup": "Prdgroup eg: ZFORK",
  "Price": "<price>"
}

1	Mandatory field
2	Mandatory field

Send Change Action

REST Mapping : /change-action

  {
    "ChangeNumber": "<Change-number>",  (1)
    "ChangeNumberDescription": "<Description>",  (2)
    "ReasonForChangeText": "<reason for change>",
    "ChangeNumberValidFromDate": "<DD-MM-YYYY>"
  }

1	Mandatory field
2	Mandatory field

Associate CA

REST Mapping : /associate-ca

{
  "Material": "<Product Name>", (1)
  "ChangeNumber": "<Change Action Name>" (2)
}

1	Mandatory field
2	Mandatory field

Send BOM

REST Mapping : /bom

NOTE: Optional fields can defaulted from extension settings as well. if EngineeringChangeDocForEdit is not added, processed without CA.

 {
"Material": "<name>", (1)
"HeaderValidityStartDate": "<DD-MM-YYYY>", (2)
"EngineeringChangeDocForEdit":"<Change Action Name>", (3)
"BOMHeaderBaseUnit": "<unit>",
"BillOfMaterialVariant": "<rev_level>",
"Plant": "<plant>",
"to_BillOfMaterialItem": [{
        "ValidityStartDate": "<DD-MM-YYYY>", (4)
        "BillOfMaterialItemCategory": "<category eg: L>",
        "BillOfMaterialItemNumber": "<line number>",
        "BillOfMaterialItemUnit": "<unit>",
        "BillOfMaterialItemQuantity": "<qty>",
        "BillOfMaterialComponent": "<material>" (5)
      },
      {
        "ValidityStartDate": "<DD-MM-YYYY>", (4)
        "BillOfMaterialItemCategory": "<category eg: L>",
        "BillOfMaterialItemNumber": "<line number>",
        "BillOfMaterialItemUnit": "<unit>",
        "BillOfMaterialItemQuantity": "<qty>",
        "BillOfMaterialComponent": "<material>" (5)
      }]
}

( 1,2,4,5 ) Mandatory field

( 3 ) if EngineeringChangeDocForEdit is not added, processed without CA.

Send Document

REST Mapping : /document

This use case supports two attachment transfer modes for sending documents to SAP S/4HANA:

URL: Sends only a URL reference to the document, which SAP S/4HANA can access remotely
FILE: Uploads the actual document content to SAP S/4HANA as an attachment

When FILE mode is used, the connector can optionally convert Microsoft Office files (Word, Excel, PowerPoint) to PDF before sending them to SAP.

URL Mode

{
  "documentName": "Material_Document.txt", (1)
  "documentType": "text/plain",
  "fileDownloadUrl": "https://host/documents/Material_Document.txt", (2)
  "businessObjectTypeName": "BUS1001006",
  "linkedSAPObjectKey": "409859", (3)
  "sendAttachmentAs": "URL" (4)
}

1	Mandatory field - the name of the document
2	Mandatory field - URL where SAP can download the document
3	Mandatory field - SAP object key to attach the document to
4	Mandatory field - specify URL

FILE Mode

For direct file uploads, send a ZIP archive containing:

payload.json - JSON metadata file with document configuration
The document file to attach (e.g., Material_Document.txt)

ZIP File Structure

The ZIP archive must contain exactly two files:

payload.json - Contains the metadata and configuration
One document file (any supported format)

Example ZIP contents:

payload.json
Material_Document.pdf

payload.json Example

{
  "documentName": "Material_Document.pdf", (1)
  "documentType": "application/pdf",
  "businessObjectTypeName": "BUS1001006",
  "linkedSAPObjectKey": "409859", (2)
  "sendAttachmentAs": "FILE", (3)
  "convertToPdf": false
}

1	Mandatory field - the name of the document file
2	Mandatory field - SAP object key (e.g., material number) to attach the document to
3	Mandatory field - specify FILE

Configuration fields like businessObjectTypeName, convertToPdf, and sendAttachmentAs can be provided in the request body or defaulted from extension settings.

CURL Example

curl -v -X POST "https://ssab.tifdemo.technia.cloud/integration/api/v1/newjob/smarteam/document" \
  -H "TIF-API-Key: ${TIF_TOKEN}" \
  -H "Content-Type: application/zip" \
  --data-binary "@/c/temp/Mtl2_Doc1.zip"

Supported File Types and Conversion

Direct Upload: All file types supported by SAP S/4HANA attachment service
PDF Conversion: Automatically converts .doc, .docx, .xls, .xlsx, .ppt, .pptx to PDF when convertToPdf: true

Error Handling

Common error scenarios:

Missing mandatory fields in payload.json
Invalid ZIP structure (missing payload.json or multiple document files)
Unsupported file type for conversion
Invalid SAP object key or business object type
Network issues accessing URL in URL mode

Check TIF Cloud logs for detailed error messages.

Send Functional Location Structure

REST Mapping : /floc-structure

Optional fields such as MaintenancePlant and GrossWeight can be supplied in the request body or defaulted from extension settings.

This use case accepts a hierarchical JSON structure. The hierarchy is defined only by the nested child arrays in the request body.

For each node, TIF generates and sends a Functional Location payload to SAP S/4HANA. If a node contains to_MaintBillOfMaterialItem, TIF also sends the corresponding Functional Location material assignment payload for that node.

The incoming FunctionalLocation value may be longer than the SAP target segment length. TIF truncates each hierarchy segment using the same level-based logic as the SAP S/4HANA connector:

level 1: last 4 characters
level 2: last 3 characters
level 3: last 3 characters
level 4: last 5 characters
level 5: last 4 characters

For example, the generated hierarchy may look like:

level 1 → 1010
level 2 → 1010-378
level 3 → 1010-378-481
level 4 → 1010-378-481-02371
level 5 → 1010-378-481-02371-5689
sibling level 3 → 1010-378-568
sibling level 2 → 1010-525

{
  "FunctionalLocation": "1010", (1)
  "FunctionalLocationName": "Engine Assembly", (2)
  "FuncnlLocLongText": "Complete engine assembly", (3)
  "MaintenancePlant": "1010",
  "GrossWeight": "500.000",
  "child": [
    {
      "FunctionalLocation": "200378", (1)
      "FunctionalLocationName": "Cylinder Head Assembly", (2)
      "FuncnlLocLongText": "Assembly containing valves and camshaft", <3>,
      "GrossWeight": "120.000",
      "to_MaintBillOfMaterialItem": [
        {
          "ValidityStartDate": "20-05-2026", (4)
          "BillOfMaterialComponent": "142065", (5)
          "BillOfMaterialItemNumber": "0010"
        },
        {
          "ValidityStartDate": "20-05-2026", (4)
          "BillOfMaterialComponent": "142064", (5)
          "BillOfMaterialItemNumber": "0020"
        }
      ],
      "child": [
        {
          "FunctionalLocation": "300481", (1)
          "FunctionalLocationName": "Cylinder Head Gasket", (2)
          "FuncnlLocLongText": "Sealing bw cylinder head and engine block", <3>,
          "child": [
            {
              "FunctionalLocation": "402371", (1)
              "FunctionalLocationName": "O-Ring Sealing System", (2)
              "FuncnlLocLongText": "O-rings for sealing oil", <3>,
              "child": [
                {
                  "FunctionalLocation": "505689", (1)
                  "FunctionalLocationName": "O-Ring Support Components", (2)
                  "FuncnlLocLongText": "Support partsproper positioning of O-rings", <3>,
                  "child": [
                    {
                      "FunctionalLocation": "605645", (1)
                      "FunctionalLocationName": "Fasteners and Retainers", (2)
                      "FuncnlLocLongText": "Bolts, clips, and retainers" (3)
                    }
                  ]
                }
              ]
            }
          ]
        },
        {
          "FunctionalLocation": "300568", (1)
          "FunctionalLocationName": "Piston Assembly", (2)
          "FuncnlLocLongText": "Piston, piston rings, and connecting rod", (3)
        }
      ]
    },
    {
      "FunctionalLocation": "200525", (1)
      "FunctionalLocationName": "Engine Cylinder Block", (2)
      "FuncnlLocLongText": "Main engine block housing cylinder", (3)
    }
  ]
}

( 1,2,3 ) Mandatory field

( 3, 5 ) Mandatory field only if material must be connected.

Send Functional Location

REST Mapping : /insert-floc

This use case sends one Functional Location item at a time. You can send either a short identifier for a single level or a full hierarchical path such as 1010-378-481-02371-4567.

If a full path is provided, TIF preserves the hierarchy in the generated SAP Functional Location identifier. Each path segment is truncated using the same level-based truncation logic described in Send Functional Location Structure.

If to_MaintBillOfMaterialItem is present, TIF also sends the Functional Location material assignment payload for the same node.

{
  "FunctionalLocation": "1010-378-481-02371-4567", (1)
  "FunctionalLocationName": "Other Accessories", (2)
  "FuncnlLocLongText": "Accessory parts for engine Sub Assy", (3)
  "MaintenancePlant": "1010",
  "GrossWeight": "0.000",
  "to_MaintBillOfMaterialItem": [
    {
      "ValidityStartDate": "20-05-2026", (4)
      "BillOfMaterialComponent": "142065", (5)
      "BillOfMaterialItemNumber": "0010"
    }
  ]
}

( 1,2,3 ) Mandatory field

( 3, 5 ) Mandatory field only if material must be connected.