Document screening API in GTS

My latest project has been building an interface for external systems to submit documents for SPL screening to our GTS instance.  SAP provides a standard API, actually a remote-enabled function module, for this very purpose: /SAPSLL/API_6800_SYNCH_MASS.

The first thing I always do with a new function module is pull up the documentation in SE37.  Unfortunately, SAP didn’t feel it was necessary to document this one.

Disabled documentation button
A disabled documentation button always looks so sad.

The next stop was Google: 7 results, mostly SDN posts, and none of which offered the comprehensive reference I needed.  I also tried an xSearch [OSS ID required] of the SAP Support Portal: 14 results here, consisting of the same SDN posts and some old OSS notes.  Bummer.  Last stop: much trial and error in the Function Module Test screen discovering which fields the FM requires you to populate and what values it expects for these fields.  Hopefully by documenting what I learned here I can save someone else the trouble.

First, let’s look at how the different table parameters relate to each other:

Table Description Cardinality
HDR_DATA This is the master table One record per document
HDR_REFERENCE_DATA Additional document attributes One record per document
HDR_PARTNER_DATA Business partner at the document header level Zero-to-many records per document
HDR_DATE_DATA Document dates Zero-to-many records per document
HDR_DIMENSION_DATA Document dimensions Zero-to-many records per document
HDR_VALUE_DATA Document value data Zero-to-many records per document
HDR_DUC_VALUE_DATA Values for Customs Duty Calculation Zero-to-many records per document
HDR_COUNTRY_DATA Document country data Zero-to-many records per document
ITM_DATA Document Line Item key fields One-to-many records per document
ITM_REFERENCE_DATA Additional item attributes One record per item
ITM_PARTNER_DATA Business partner at the item level Zero-to-many records per item
ITM_DATE_DATA Item dates Zero-to-many records per item
ITM_DIMENSION_DATA Item dimensions Zero-to-many records per item
ITM_VALUE_DATA Item value data Zero-to-many records per item
ITM_DUC_VALUE_DATA Values for Customs Duty Calculation Zero-to-many records per item
ITM_PREFERENCE_DATA Legal regulation preferences Zero-to-many records per item
DOC_ADDRESS_DATA Partner address Zero-to-one record per partner (either header or item level)
Output Tables
RESULT_LEGAL_CONTROL Results of any screens or checks performed by GTS One-to-many records per document
RETURN Results of the function call One-to-many records per document
MAP_ERR List of mapping errors Zero-to-many records per document

There’s a couple other tables that are used for output.  We’ll get to those later.  Now let’s look at the fields in each table. I’ve highlighted the required fields.  The function module will fail if no value is passed for any of these fields.

HDR_DATA

Note: Some optional fields omitted for brevity.

Field Type Description
REFNO_HEADER CHAR(40) External document number, used as unique identifier
APPLICATION_LEVEL CHAR(4) Used for mapping feeder system organization units (document types, item categories, partner functions) to SAP organization units.  List of possible values can be found in the Value Range for the domain /SAPSLL/APEVS.
DOCUMENT_TYPE CHAR(5) Must be defined (via config) in /SAPSLL/TLEBGS or /SAPSLL/TLEBVS.  Valid entries are defined based on the Logical System Group and the Application Level.
COMPANY_CODE CHAR(4) Must be a valid company code

HDR_REFERENCE_DATA

Field Type Description
REFNO_HEADER CHAR(40) ID, same value as the field on the HDR_DATA table
QUAL_REFNO CHAR(6) ‘EXTID’ for Document, ‘EXTIDF’ for Document Flow
REFNO CHAR(40) Free-form reference number
REFDAT DATE Date for reference object
ORG_LOGSYSTEM CHAR(10) The logical system (not logical system group) representing the feeder system passing this data
OBJTP CHAR(10) The object type of the document (Ex: BUS2032 for sales orders)
REFAPP CHAR(10) The object type of the document (Ex: BUS2032 for sales orders)
ERNAM CHAR(12) Name of user who created the object
AENAM CHAR(12) Name of user who last changed the object
BUS_TRANSAC_DOC_TYPE_CODE CHAR(5)

HDR_PARTNER_DATA

Note: Some optional fields omitted for brevity.

Field Type Description
REFNO_HEADER CHAR(40) ID, same value as the field on the HDR_DATA table
DELETION_INDICATOR CHAR(1) Set to ‘X’ to remove the partner from the document.
PARTNER_FUNCTION CHAR(8) Must be defined (via config) in /SAPSLL/TLERGS or /SAPSLL/TLERVS for the specified logical system.  You can pass multiple partners with the same partner function.
PARTNER_TYPE CHAR(2) Range of possible values can be found in the value list for the domain /SAPSLL/BPTYP.  You can pass multiple partners of the same type.
PARTNER_ID CHAR(40) The external ID of the partner.  Must be defined for the specified logical system and partner type.
ADDR_NO CHAR(10) The address number of the address in the DOC_ADDRESS_DATA table that corresponds to this partner.  Only required if this address is different than the standard address defined in GTS for this partner.
ADDR_MANIPULATED CHAR(1) Set to ‘X’ to override the standard address for this partner with the address from the DOC_ADDRESS_DATA table.  The override applies only to this document.  If you pass a space then GTS will ignore the address in the DOC_ADDRESS_DATA table and will use the standard address for the partner.

HDR_DATE_DATA

Field Type Description
REFNO_HEADER CHAR(40) ID, same value as the field on the HDR_DATA table
TYPE_OF_DATE CHAR(6) List of possible values can be found in table /SAPSLL/TCO260.
REL_POINT_IN_TIME_TS TIMESTAMP Consists of a date + 24hr time in the user-specified date format.  (Ex: 02/06/2011 00:00:00)

HDR_DIMENSION_DATA

Field Type Description
REFNO_HEADER CHAR(40) ID, same value as the field on the HDR_DATA table
QUAL_DIM CHAR(6) Dimension type. List of possible values can be found in table /SAPSLL/TCO220.
DIMEN QUAN(19) Dimension value
DIMEN_FLT FLOAT Dimension value as a 16-digit floating point number.
DIM_UOM UNIT(3) Unit of measure.  List of possible values can be found in table T006.
DIM_UOM_ISO CHAR(3) Unit of measure ISO code

HDR_VALUE_DATA

Field Type Description
REFNO_HEADER CHAR(40) ID, same value as the field on the HDR_DATA table
QUAL_VAL CHAR(6) Value type. List of possible values can be found in table /SAPSLL/TCO240.
VALUE QUAN(19) Value
VALUE_FLOAT FLOAT Value as a 16-digit floating point number.
VAL_CURR CUKY(5) Currency key for value. List of possible values can be found in table TCURC.
VAL_CURR_ISO CHAR(3) ISO currency code

HDR_DUC_VALUE_DATA

Field Type Description
REFNO_HEADER CHAR(40) ID, same value as the field on the HDR_DATA table
QUAL_VAL CHAR(6) Value type. List of possible values can be found in table /SAPSLL/TCO240.
VALUE QUAN(19) Value
VALUE_FLOAT FLOAT Value as a 16-digit floating point number.
VAL_CURR CUKY(5) Currency key for value. List of possible values can be found in table TCURC.
VAL_CURR_ISO CHAR(3) ISO currency code
CVRTQ DEC(9,5) Indirect Quoted Exchange Rate

HDR_COUNTRY_DATA

Field Type Description
REFNO_HEADER CHAR(40) ID, same value as the field on the HDR_DATA table
SEQUENCE_NUMBER NUMC(5) Incremental sequence number, must be unique within a REFNO_HEADER value
DEPARTURE_COUNTRY CHAR(3) Country of Departure Key
DEPARTURE_COUNTRY_ISO CHAR(2) Country of Departure ISO Code
ARRIVAL_COUNTRY CHAR(3) Country of Destination Key
ARRIVAL_COUNTRY_ISO CHAR(2) Country of DestinationISO Code

ITM_DATA

Note: Some optional fields omitted for brevity.

Field Type Description
REFNO_HEADER CHAR(40) ID, same value as the field on the HDR_DATA table
ITEM_NUMBER CHAR(10) Unique ID for the item.  Must be unique within a REFNO_HEADER value.
LEGAL_ACTIVE CHAR(1) Set to ‘X’ if the item is active.  The item will not be screened if this is not set.
RECHECK_INDICATOR CHAR(1) Set to ‘X’ if the item should be checked again.
ITEM_CATEGORY CHAR(5) Must be a valid item category for the specified Application Level and Logical System Group
PRODUCT_ID CHAR(40) Product number.  Must be valid for the specified Logical System Group.
PLANT CHAR(4) Must be a valid plant code.

ITM_REFERENCE_DATA

Field Type Description
REFNO_HEADER CHAR(40) ID, same value as the field on the HDR_DATA table
ITEM_NUMBER CHAR(10) Unique ID for the item corresponding to the value on the ITM_DATA table.
QUAL_REFNO CHAR(6) ‘EXTID’ for Document, ‘EXTIDF’ for Document Flow
REFNO CHAR(40) Reference number.  Free-form field, you can use it for whatever purpose you choose.
REFDAT DATE Reference date
ORG_LOGSYSTEM CHAR(10) The logical system (not logical system group) representing the feeder system passing this data
OBJTP CHAR(10) The object type of the reference document.
REFAPP CHAR(10) The application level of the reference document.
ERNAM CHAR(12) Name of User Who Created the Object
AENAM CHAR(12) Name of User Who Changed the Object
HG_LV_ITEM CHAR(10) Higher-Level Document Item
BUS_TRANSAC_DOC_TYPE_CODE CHAR(5)
BUS_TRANSAC_DOC_ITM_ID CHAR(10)

ITM_PARTNER_DATA

Field Type Description
REFNO_HEADER CHAR(40) ID, same value as the field on the HDR_DATA table
ITEM_NUMBER CHAR(10) Unique ID for the item corresponding to the value on the ITM_DATA table.
DELETION_INDICATOR CHAR(1) Set to ‘X’ to remove the partner from the document.
PARTNER_FUNCTION CHAR(8) Must be defined (via config) in /SAPSLL/TLERGS or /SAPSLL/TLERVS for the specified logical system.
PARTNER_TYPE CHAR(2) Range of possible values can be found in the value list for the domain /SAPSLL/BPTYP.
PARTNER_ID CHAR(40) The external ID of the partner. Must be defined for the specified logical system and partner type.
ADDR_NO CHAR(10) The address number of the address in the DOC_ADDRESS_DATA table that corresponds to this partner. Only required if this address is different than the standard address defined in GTS for this partner.
ADDR_MANIPULATED CHAR(1) Set to ‘X’ to override the standard address for this partner with the address from the DOC_ADDRESS_DATA table. The override applies only to this document.

ITM_DATE_DATA

Field Type Description
REFNO_HEADER CHAR(40) ID, same value as the field on the HDR_DATA table
ITEM_NUMBER CHAR(10) Unique ID for the item corresponding to the value on the ITM_DATA table.
TYPE_OF_DATE CHAR(6) List of possible values can be found in table /SAPSLL/TCO260.
REL_POINT_IN_TIME_TS TIMESTAMP Consists of a date + 24hr time in the user-specified date format. (Ex: 02/06/2011 00:00:00)

ITM_DIMENSION_DATA

Field Type Description
REFNO_HEADER CHAR(40) ID, same value as the field on the HDR_DATA table
ITEM_NUMBER CHAR(10) Unique ID for the item corresponding to the value on the ITM_DATA table.
QUAL_DIM CHAR(6) Dimension type. List of possible values can be found in table /SAPSLL/TCO220.
DIMEN QUAN(19) Dimension value
DIMEN_FLT FLOAT Dimension value as a 16-digit floating point number.
DIM_UOM UNIT(3) Unit of measure. List of possible values can be found in table T006.
DIM_UOM_ISO CHAR(3) Unit of measure ISO code

ITM_VALUE_DATA

Field Type Description
REFNO_HEADER CHAR(40) ID, same value as the field on the HDR_DATA table
ITEM_NUMBER CHAR(10) Unique ID for the item corresponding to the value on the ITM_DATA table.
QUAL_VAL CHAR(6) Value type. List of possible values can be found in table /SAPSLL/TCO240.
VALUE QUAN(19) Value
VALUE_FLOAT FLOAT Value as a 16-digit floating point number.
VAL_CURR CUKY(5) Currency key for value. List of possible values can be found in table TCURC.
VAL_CURR_ISO CHAR(3) ISO currency code

ITM_DUC_VALUE_DATA

Field Type Description
REFNO_HEADER CHAR(40) ID, same value as the field on the HDR_DATA table
ITEM_NUMBER CHAR(10) Unique ID for the item corresponding to the value on the ITM_DATA table.
QUAL_VAL CHAR(6) Value type. List of possible values can be found in table /SAPSLL/TCO240.
VALUE QUAN(19) Value
VALUE_FLOAT FLOAT Value as a 16-digit floating point number.
VAL_CURR CUKY(5) Currency key for value. List of possible values can be found in table TCURC.
VAL_CURR_ISO CHAR(3) ISO currency code
CVRTQ DEC(9,5) Indirect Quoted Exchange Rate

ITM_PREFERENCE_DATA

Note: I haven’t used this table so there may be more required fields than the ones I have highlighted.

Field Type Description
REFNO_HEADER CHAR(40) ID, same value as the field on the HDR_DATA table
ITEM_NUMBER CHAR(10) Unique ID for the item corresponding to the value on the ITM_DATA table.
LGREG CHAR(5) Legal Regulation. Possible values can be found in table /SAPSLL/T606G.  (Ex: ‘NAFTA’)
PFONY CHAR(1) Rule set type.  ‘A’ for NAFTA, ‘B’ for EU.
LGREG_APPLIED CHAR(1) Set to ‘X’ if agreement was used for this document item
PREF_INDICATOR CHAR(3) [space] – Not Eligible for Preferential Treatment
X – Eligible for Preferential Treatment
A – Goods wholly obtained or produced entirely
B – Goods satisfy specific rules of origin
C – Goods entirely from originating materials
N/E – Not Eligible
PREF_METHOD CHAR(1) Comparison method – specifies how the system determines the preference eligibility of a product.   List of possible values can be found in the Value Range for domain /SAPSLL/PRMET.0 – External Preference Document (Vendor/Manual)
1 – Transaction Value Method
2 – Net Cost Method
3 – Tariff Alternation (NAFTA)
PRICE_DEPENDENT CHAR(1) Set to ‘X’ if value is price-dependent.
PRICE_UNIT DEC(5) The “price per” unit.
PRICE_UOM CHAR(3) Unit of measure. List of possible values can be found in table T006.
PRICE_UOM_ISO CHAR(3) ISO UOM code
VAL_CURR CUKY(5) Currency key of the value
VAL_CURR_ISO CHAR(3) ISO currency code
VALCP DEC(20,3) Value as a decimal.
VALCP_FLT FLOAT Value as a 16-digit floating point number.
VALOR DEC(20,3) Value as a decimal.
VALOR_FLT FLOAT Value as a 16-digit floating point number.
VALNO DEC(20,3) Value as a decimal.
VALNO_FLT FLOAT Value as a 16-digit floating point number.
VALRB DEC(20,3) Value as a decimal.
VALRB_FLT FLOAT Value as a 16-digit floating point number.

DOC_ADDRESS_DATA

Note: Some optional fields omitted for brevity.

Field Type Description
ADDR_NO CHAR(10) Unique ID for this address.  Referenced from the HDR_PARTNER_DATA and ITM_PARTNER_DATA tables.
FORMOFADDR CHAR(20) Language-dependent form of address
NAME CHAR(40) Name 1
NAME_2 CHAR(40) Name 2
NAME_3 CHAR(40) Name 3
NAME_4 CHAR(40) Name 4
COUNTRY CHAR(3) Valid Country Key

RESULT_LEGAL_CONTROL

Each row in this table is either for the document header or one of the items.  If it is for the header, SERV_STAH and QUAL_STAH will be populated while ITEM_NUMBER, SERV_STAI, and QUAL_STAI will all be empty.  If it is for an item, ITEM_NUMBER, SERV_STAI, and QUAL_STAI will be populated while SERV_STAH and QUAL_STAH will be empty.  All the services and their corresponding status categories can be found in the table /SAPSLL/TCO210.

Field Type Description
DOCUMENT_NUMBER CHAR(40) External document ID.  Will match what is passed in the REFNO_HEADER field of the input tables.
GUID_HEADER CHAR(32) The Global Unique Identifier generated by GTS to identify this document.
SERV_STAH CHAR(6) Header Status Management Service
QUAL_STAH CHAR(6) Header Status Category for the Status Management Service above.
ITEM_NUMBER CHAR(10) External item number.
GUID_ITEM CHAR(32) The Global Unique Identifier generated by GTS to identify this item.
SERV_STAI CHAR(6) Item Status Management Service
QUAL_STAI CHAR(6) Item Status Category for the Status Management Service above.
SERVIC_TEXT CHAR(60) Text for the Status Management Service, either SERV_STAH or SERV_STAI, whichever is populated.
STATUS_TEXT CHAR(25) Text for the Status Category, either QUAL_STAH or QUAL_STAI, whichever is populated.
CHANGED_AT TIMESTAMP When the status was last updated.  Practically, this can be used as the timestamp when the document was screened.
CD_ACCESS CHAR(1) ‘X’ if the function module /SAPSLL/API_6800_STATUS_GET could not find the status of the document header.
ENQUEUE CHAR(1) ‘X’ if the API was unable to lock an existing document prior to updating it.
ENQUEUE_PRE CHAR(1) ‘X’ if the API was unable to lock a previous document prior to updating the document flow.
ORG_UNIT CHAR(1) ‘X’ if the API was unable to determine the document’s Foreign Trade Organization.  This is configured based on company code and logical system.
DOCUMENT_TYPE CHAR(1) ‘X’ if an invalid document type was passed on the HDR_DATA table.
ITEM_CATEGORY CHAR(1) ‘X’ if an invalid item category was passed on the ITM_DATA table.
LOG_SYSTEM CHAR(1) ‘X’ if an invalid logical system value was passed on the HDR_REFERENCE_DATA or ITM_REFERENCE_DATA table.
PARTNER CHAR(1) ‘X’ if an invalid partner was passed on the HDR_PARTNER_DATA or ITM_PARTNER_DATA table.
PARTNER_FUNCTION CHAR(1) ‘X’ if an invalid partner function is passed on the HDR_PARTNER_DATA or ITM_PARTNER_DATA table.
PRODUCT CHAR(1) ‘X’ if an invalid product number was passed in the ITM_DATA table.  Also could indicate a configuration problem, like if the product is not configured with a license service (‘LECLDT’).
NUMBER_RANGE CHAR(1) ‘X’ if the API is unable to determine the document number for a new document.  The number range is configured based on the customs document type which in turn is configured by logical system group.
CHECK_IND CHAR(1) Compliance Management Check result
A – Check Okay
B – Compliance Management Block
C – Technical Error Block
BOM_SUBITEM CHAR(10)

RETURN

This table is the standard BAPI return table.  If the call was successful there will be at list one entry in this table with a type of ‘S’.

Field Type Description
TYPE CHAR(1) Message type: S Success, E Error, W Warning, I Info, A Abort
ID CHAR(20) Message Class
NUMBER NUMBER Message Number
MESSAGE CHAR(220) Message Text
LOG_NO CHAR(20) Application log number
LOG_MSG_NO NUMBER Application log message number
MESSAGE_V1 CHAR(50) Message Variable
MESSAGE_V2 CHAR(50) Message Variable
MESSAGE_V3 CHAR(50) Message Variable
MESSAGE_V4 CHAR(50) Message Variable
PARAMETER CHAR(32) The parameter table containing the invalid value. Not always populated.
ROW NUMBER The line in the parameter table containing the invalid value. Not always populated.
FIELD CHAR(30) The field containing the invalid value.  Not always populated.
SYSTEM CHAR(10) The logical system of the GTS environment.

MAP_ERR

This table lists all the mapping errors resulting from invalid parameter values or incorrect configuration.  Sometimes you have to do a little detective work to interpret these results.  For example, if you use an invalid plant code this table will have the plant code in the OBJ_NUM field with an OBJT value of ‘F’ (Legal Unit) since the legal unit is derived from the plant code.

Field Type Description
DOCUMENT_NUMBER CHAR(40) External document ID.  Will match what is passed in the REFNO_HEADER field of the input tables.
OBJT CHAR(1) The type of the invalid valueA – Partner
B – Material
C – Item Category
D – Partner Function
E – Foreign Trade Organization
F – Legal Unit
OBJ_NUM CHAR(40) The invalid value

1 comment on Document screening API in GTS