Ansicht
Dokumentation

SO_DOCUMENT_RECEIVE_API1 - SAPoffice: Receiving external documents with attachments

PERFORM Short Reference BAL Application Log Documentation
This documentation is copyright by SAP AG.

Functionality

This function module enables the receipt of a single document sent externally, including any attachments. Once the document has arrived in the target system, the function module places the document in the inboxes of the recipients specified in the table RECEIVERS. The sender of the document becomes the owner of the document; the creator of the document, however, is the user who executed the function module. A special user is usually responsible for handling incoming mails.

A distinction must be made here between the document and its folder entries. The document itself only exists once in the database. It serves as a template for the folder entries and can be addressed by way of its object ID. The document can have any number of folder entries. They contain the contents and attributes of the document as well as some additional attributes related to the folder entry. These include the sender priority and the expiration date of the entry. Folder entries are the result of resubmissions, links, sending and creating a new document.

Import Parameters

RECEIVE_INFO

This structure contains information about the sender of the document. The dates on which the document was created and sent can also be specified. These structure fields can be left empty, in which case the information is completed automatically.

COMM_ID

Unique ID of the communication process. This is used primarily when sending items using X.400. If it is not specified, a new unique ID is created.

SENDER

Address of the sender

The following entry categories are possible:

SAP user name of the sender

SAPoffice name of the sender

Fax number in the form of the structure SADRFD

Internet address in the form of the structure SADRUD

Remote SAP address in the form of the structure SADR7D

X.400 address in the form of the structure SADR8D

ADR_TYPE

Type of the SENDER entry

The following values are possible:

'B ' : SAP user name

' ' : SAPoffice name

'FAX' : fax number

'SMTP' : Internet address

'SAP ' : Remote SAP address

'X400' : X.400 address

REPLY_TO

If this field is filled, the document sent is regarded as a reply to the communication identified by the ID specified. A correspondence history is set up and recorded automatically.

SEND_DATE

Date on which the document was sent

SEND_TIME

Time at which the document was sent

CREAT_DATE

Date on which the original document was created

CREAT_TIME

Time at which the original document was created

DOCUMENT_DATA

This structure must contain the attributes of the document to be sent.

OBJ_NAME

Name of the document.

OBJ_DESCR

Title (short description) of the document.

OBJ_LANGU

Language of the document.

OBJ_SORT

Sort field of the document. This string can be used as a search term in the attribute search.

OBJ_EXPDAT

Expiration date of the document. The document itself cannot expire, however, for every new folder entry of the document this date is used as a reference for the expiration date of the entry (field EXPIRY_DAT).

SENSITIVTY

Sensitivity of the document:

A private document can have the following levels of sensitivity:

'O': Standard, normal sensitivity

'F': Functional, can be forwarded functionally

'P': confidential, not visible to substitute

For documents in shared folders only sensitivity 'O' is allowed.

OBJ_PRIO

Recipient priority. The document itself does not have a priority, however, for every new folder entry of the document this value is used as a reference for the recipient priority of the entry (field PRIORITY).

NO_CHANGE

If this flag is set ('X'), only the author can change the document using shared folder entries. In the case of private folder entries, the author can also make changes after the document has been sent.

PRIORITY

Recipient priority for the folder entry. This value represents the importance assigned to the entry by the owner after it has been received.

EXPIRY_DAT

Expiration date of the folder entry. When the expiration date has been reached or exceeded, the entry is placed in the private trash and can be retrieved from there if necessary before the trash is next emptied. A new folder entry is initially supplied with the expiration date of the document from the field OBJ_EXPDAT.

PROC_TYPE

If this field is not initial (not ' '), the document can be processed.

The following entries are allowed:

'D': dialog module

'F': Function Module

'R': Report

'S': report with value transfer to global memory

'T': Transaction

'U' : transaction with value transfer to global memory

PROC_NAME

Processing element. Depending on the entry in the field PROC_TYPE, the name of the dialog module, function module, report, or transaction must be specified.

PROC_SYST

Name of the system in which the document will be processed. If no system is specified or the value '*', processing can be carried out in any system.

PROC_CLINT

Client in which the document will be processed. If no client is specified or the value '*', processing can be carried out in any client.

SKIP_SCREN

If this flag is set ('X'), the first screen is skipped in the processing.

TO_DO_OUT

If this flag is set ('X'), the document cannot be acted upon from the SAPoffice interface. It must be processed outside of SAPoffice via the API function module SO_DOCUMENT_SET_STATUS_API1.

FREE_DEL

If this flag is set ('X'), the document can also be deleted in other folders via the API.

DOC_SIZE

Size of the document in bytes. In the case of PC documents, the size of the respective file should be entered here, in the case of RAW and SCR documents, the size is calculated from the "length of the last line" + "number of remaining lines multiplied by 255".

Export parameters

SENT_TO_ALL

If this flag is set ('X'), the document was sent to all specified recipients or (if forwarded externally) the correct send requests were submitted to a subsystem. This flag is not set if at least one party did not receive the document.

NEW_OBJECT_ID

Object ID of the document created by the receive operation.

COMMUNICATION_ID

Unique ID of the communication process. If the import parameter RECEIVE_INFO-COMM_ID was filled, this value is used; otherwise the new ID is used.

Table Parameter

PACKING_LIST

This table requires information about how the data in the tables OBJECT_HEADER, CONTENTS_BIN and CONTENTS_TXT are to be distributed to the documents and its attachments. The first row is for the document, the following rows are each for one attachment.

TRANSF_BIN

If this flag is activated ('X'), the table entry describes an object stored in binary format. The content of the object is in the table CONTENTS_BIN. If the flag is not activated, the object content is in the table CONTENTS_TXT in ASCII format.

HEAD_START

Requires the start row of the table OBJECT_HEADER, as of which the specific header data of the object is stored.

HEAD_NUM

Requires the number of rows in the table OBJECT_HEADER that contain specific header data for the object. The relevant rows are arranged in a block and defined uniquely together with the entry in HEAD_START.

BODY_START

Requires the start row of the table dependent on the TRANSF_BIN flag as of which the object content is stored.

BODY_NUM

Requires the number of rows of the table dependent on the flag TRANSFER_BIN, which contain the object content. The relevant rows are arranged in a block and defined uniquely together with the entry in HEAD_START.

DOC_TYPE

Attachment type. In the first row of the table, this field is not used.

OBJ_NAME

Name of the attachment. In the first row of the table, this field is not used.

OBJ_DESCR

Title (short description) of attachment. In the first row of the table, this field is not used.

OBJ_LANGU

Attachment language. In the first row of the table, this field is not used.

DOC_SIZE

Attachment size in bytes. For PC objects, the size of the relevant file should be entered here. For RAW and SCR objects, the size is the "length of the last page" + "number of other rows multiplied by 255". In the first row of the table, this field is not used.

MESS_TYPE

This field is not used.

OBJECT_HEADER

This table must contain the summarized data dependent on each object type. SAPscript objects store information here about forms and styles, for example. Excel list viewer objects store the number of rows and columns amongst other things and PC objects store their original file name.

LINE

Requires the type-dependent data of the object line by line. The fields HEAD_START and HEAD_NUM in the table PACKING_LIST define which section belongs to which object.

CONTENTS_BIN

This table must contain the summarized content of the objects identified as binary objects.

LINE

Requires the object content line by line. The fields BODY_START and BODY_NUM in the table PACKING_LIST define which section belongs to which object.

CONTENTS_TXT

This table must contain the summarized content of objects flagged as ASCII objects.

LINE

Requires the object content line by line. The fields BODY_START and BODY_NUM in the table PACKING_LIST define which section belongs to which object.

OBJECT_PARA

The table is only needed if the document to be sent is to be processed. The table must contain SET/GET parameters that are transferred to the processing element during processing.

It is not possible to transfer processing parameters to the document attachment.

NAME

Name of SET/GET parameter. Only the first three characters are used.

OPTION

This field is not used.

Contains the corresponding value of the parameter in NAME.

HIGH

This field is not used.

OBJECT_PARB

This table is only used by documents to which a particular processing type is assigned. Depending on this, they have a different meaning. If the processing element is a report or transaction that passes values to the global memory, the table content is interpreted as a set of parameters and values and is exported to the memory ID taken from the first row. If the processing element is a function or dialog module, the table is passed to it as the table parameter MSGDIAL.

It is not possible to transfer processing parameters to the document attachments.

NAME

If the processing element is a report or transaction that passes values to the global memory, the field of the first table row must contain the name of the memory ID used for the export. The fields of the other lines are used to contain the names of the parameters. If the processing element is a function module or a dialog module, the fields must contain values corresponding to the use of the module.

VALUE

If the processing element is a report or transaction with value transfer to the global memory, the field of the first table line must remain blank. The fields of the other lines are used to contain the values for the parameters in NAME. If the processing element is a function or dialog module, the fields must be assigned values appropriately according to the use.

RECEIVERS

This table must contain the document recipients.

RECEIVER

Recipient name.

The following entry categories are possible:

SAP user name of the recipient

SAPoffice name of the recipient

a shared distribution list

Fax number in the form of the structure SADRFD

Internet address in the form of the structure SADRUD

Remote SAP name in the form of the structure SADR7D

X.400 address in the form of the structure SADR8D

ADR_TYPE

Type of the RECEIVER entry

The following values are possible:

'B ' : SAP user name

' ' : SAPoffice name

'C' : general distribution list

'F': fax number

'U' : Internet address

'R': remote SAP name

'X': X.400 address

REC_ID

If the recipient is a SAPoffice user, the user ID, instead of the recipient name in RECEIVER, can be entered in this field.

REPLY_DOC

If this field is filled, the document sent is regarded as a reply to the folder entry identified by the ID specified. A correspondence history is set up and recorded automatically.

REC_DATE

The date on which the document is to reach the recipient. This date cannot be guaranteed for external recipients, as it depends on connected products.

PROXY_ID

If automatic forwarding is active in the recipient's system, this field contains the SAP user ID or the address ID of the external address, to which the document was ultimately sent.

RETRN_CODE

When the recipient has received the document, the function module enters the value '0' in this field. If the document is not successfully received, a value unequal to '0' is entered in the field.

EXPRESS

If this flag is activated ('X'), the document is sent with the attribute 'express'. If the recipient is a logged-on SAPoffice user, he or she receives a message immediately, saying that he or she has received an express mail.

COPY

If this flag is activated ('X'), the document is sent with the attribute 'copy'.

BLIND_COPY

If this flag is activated ('X'), the document is sent with the attribute 'secret copy'. If the recipient is a SAPoffice user, he or she can neither print nor forward the document.

NO_FORWARD

If this flag is activated ('X') and the recipient is a SAPoffice user, he or she cannot forward the document.

NO_PRINT

If this flag is activated ('X') and the recipient is a SAPoffice user, he or she cannot print the document.

TO_ANSWER

If this flag is activated ('X') and the recipient is a SAPoffice user, the user must reply to the document before he or she can delete it from his or her inbox.

TO_DO_EXPL

If this flag is activated ('X') and the recipient is a SAPoffice user, the user must process the document before he or she can delete it from his or her inbox.

TO_DO_GRP

If this field contains a value between '1' and '9', a SAPoffice user in the recipient group indicated by this number must process the document before the recipients can delete it from their inboxes. If the value '0' is entered, the document does not need to be processed.

COM_TYPE

Communication type used to send the document. This field is only relevant if the recipient is an address number, that is, if the document is sent externally via address management. If the field is empty, the standard communication type specified in address management is used.

The following values are possible:

'INT' : Send using Internet

'FAX' : Send using fax

'X40' : Send using X.400

'RML' : Send to another SAP system

LFDNR

Current number from address management. This field is only relevant if the recipient is an address number, that is, if the document is sent using address management. If the field is empty, the default current number in address management is used.

This field is not used.

COUNTRY

This field is not used.

SPOOL_ID

This field is not used.

NOTIF_DEL

If this flag is set ('X'), the sender is notified as soon as the document is sent to the recipient. A notification is also sent if the document could not be sent. This flag should only be set if documents are sent externally, since internally the send process is carried out synchronously. Confirmation is only supported by a small number of mail systems, however (X.400 and SAP, for example).

NOTIF_READ

If this flag is set ('X'), the sender is notified as soon as the recipient as read the document. This flag should only be set if documents are sent externally, since internally the send process is carried out synchronously. Read confirmation is only supported by a small number of mail systems, however (X.400 and SAP, for example).

NOTIF_NDEL

If this flag is set ('X'), the recipient is notified if the document cannot be sent to the recipient. This flag should only be set if documents are sent externally, since internally the send process is carried out synchronously. This notification is only supported by a small number of mail systems, however (X.400 and SAP, for example).

SAP_BODY

SAP_BODY If this flag is activated ('X'), SAP specific data is transferred to the document in an external body part when sending via X.400. This only makes sense if the target system is an SAP system.

Exceptions

TOO_MANY_RECEIVERS

Too many recipients were specified. The active user does not have authorization to send to this number of recipients.

DOCUMENT_NOT_SENT

The document could not be sent. It was not delivered to any of the specified recipients.

DOCUMENT_TYPE_NOT_EXIST

A document class assigned to the document or attachment does not exist or is invalid.

OPERATION_NO_AUTHORIZATION

The document could not be sent. One of the authorizations required is missing.

PARAMETER_ERROR

An invalid combination of parameter values was transferred to the function module.

X_ERROR

An internal error or a database inconsistency occurred.

ENQUEUE_ERROR

A lock required for the send process could not be set. It may be being processed by another user.

Example

FORM routine for sending documents. Any errors are listed in a log file.

FORM RECEIVE_EXTERN_DOC TABLES OBJPACK STRUCTURE SOPCKLSTI1

OBJHEAD STRUCTURE SOLISTI1

OBJBIN STRUCTURE SOLISTI1

OBJTXT STRUCTURE SOLISTI1

OBJPARA STRUCTURE SOPARAI1

OBJPARB STRUCTURE SOPARBI1

RECLIST STRUCTURE SOEXTRECI1

USING VALUE(REC_INFO) STRUCTURE SORECINFI1

VALUE(DOC_CHNG) STRUCTURE SODOCCHGI1

RCODE.

DATA: F_SENT LIKE SONV-FLAG.

CALL FUNCTION 'SO_DOCUMENT_RECEIVE_API1'

EXPORTING

RECEIVE_INFO = REC_INFO

DOCUMENT_DATA = DOC_DATA

IMPORTING

SENT_TO_ALL = F_SENT

TABLES

PACKING_LIST = OBJPACK

OBJECT_HEADER = OBJHEAD

CONTENTS_BIN = OBJBIN

CONTENTS_TXT = OBJTXT

OBJECT_PARA = OBJPARA

OBJECT_PARB = OBJPARB

RECEIVERS = RECLIST

EXCEPTIONS

TOO_MANY_RECEIVERS = 1

OBJECT_NOT_SENT = 2

DOCUMENT_TYPE_NOT_EXIST = 3

OPERATION_NO_AUTHORIZATION = 4

PARAMETER_ERROR = 5

X_ERROR = 6

ENQUEUE_ERROR = 7.

RCODE = SY-SUBRC.

CASE RCODE.

WHEN 1.

PERFORM WRITE_TO_LOGFILE