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.
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 |
Advertisement
