consolut - CL_BDS_DOCUMENT_SET - BusinessDocumentSet

CL_BDS_DOCUMENT_SET - BusinessDocumentSet

General Material Data BAL Application Log Documentation
This documentation is copyright by SAP AG.

Functionality

The Business Document Service (BDS) provides general and easily integratable document management functionsfor SAP applications. The central component of these functions is the Business Document Navigator (BDN)navigation interface. This user interface enables users to interactively perform document management functions (displaying, creating and deleting, for example).

The BDS is strongly linked with the business processes in an enterprise, expressed in particular ingeneral object relationships. Together with SAP Desktop Office Integration, the BDS represents a software solution package for the integration of general desktop office applications.

The BDS has the following features:

Simple handling of desktop office products

Support of scenarios for

Authoring

Publishing

Retrieval

Storing private and shared documents

User interface for

Attribute assignment

Classification

Detailed information and document information

Displaying

Changing

Navigation

Connection to the Change & Transport System

Class CL_BDS_DOCUMENT_SET is a central component of the BDS.

The BDS provides an interface that typically works on the basis of identifying a business document setand context information. For identification, the application needs to know only its own logical system, its class name, possibly its client and its object key.

The CL_BDS_DOCUMENT_SET functions can be divided into two groups: general functions, which relate to the Business Document Set and specific functions:

General functions

DELETE

GET_INFO

GET_INFO_NEWEST_ONLY

CALL_NAVIGATOR

CONFIRM_CREATE/_UPDATE

CREATE_WITH_FILES/_URL/_TABLE/AS_TABLE

UPDATE_WITH_FILES/_URL/_TABLE/AS_TABLE

GET_WITH_FILES/_URL/_TABLE/AS_TABLE

DELETE_PROPERTIES

CHANGE_PROPERTIES

Specific functions

Functions for versions and variants

- CREATE_VERSION_WITH_FILES/_URL/_TABLE/AS_TABLE

- CREATE_VARIANT_WITH_FILES/_URL/_TABLE/AS_TABLE

Functions for relations

- GET_RELATIONS

- CREATE_RELATION

- DELETE_RELATIONS

- QUERY_RELATIONS

Functions for transport

- GET_TRANSPORT_INFOS

Parameters

Application objects are identified by the following parameters:

LOGICAL_SYSTEM

Logical system, ID of SAP System instance

CLASSNAME

Class name, name of application class

CLASSTYPE

Class type, type of application class

OBJKEY

Object key

CLIENT

Client
This parameter is optional other than for client-dependent documents, where it must be used.

The application object is identified and the relevant Document Set determined by a query of all documents that are assigned to this application object.

Individual documents are specified by the following parameters:

DOC_ID

Document identification

DOC_VER_NO

Document version number

DOC_VAR_ID

Document variant identification

Tables

Signature table

Documents are identified by the parameter SIGNATURE using the signature table. This table is used toperform both the query and the reply: If you specify what you know about the document or documents concerned,you are given the number of documents that correpsond to the criteria. The attributes of one or more documents can be transferred in the signature table. The signature table has the following fields:

DOC_COUNT

Document counter
This field counts indivdual document variants. There can be several entries per variant, but the individual entries differ only in attribute name and attribute value.

DOC_ID

Document identification

DOC_VER_NO

Document version number

DOC_VAR_ID

Document variant identification

DOC_VAR_TG

Document variant tag
The type of variant is specified A variant can have three forms:

Original

Language variant

Format variant

COMP_COUNT

Component counter

PROP_NAME

Attribute name

PROP_VALUE

Attribut value

The more fields you specify, the fewer hits will be found. This means that you can restrict the search to a single variant, for example.

Component table

The table COMPONENTS concerns components of a document set. Components for a number of documents can be transferred:

DOC_COUNT

Document counter
This field counts the individual document variants. There can be several entries per variant. If this is the case, the individual entries differ only in attribute name and attribute value.

COMP_COUNT

Component counter for a document

COMP_ID

Component identification

MIMETYPE

MIME type of component

COMP_SIZE

Size of component

File table

The table FILES is used for handling document content using local files. It contains the following fields:

DOC_COUNT

Document counter
This field counts individual document variants. There can be several entries per variant. If this is the case, the individual entries differ only in attribute name and attribute value.

COMP_COUNT

Component counter
This counts the components of a document.

DIRECTORY

Name of source directory

FILENAME

File name

MIMETYPE

MIME type of component

URL table

The content is transferred via URLs in the URL table, that is, complete URLs are transferred. This specifies where the documents can be stored. The URL table has the following fields:

DOC_COUNT

COMP_COUNT

Component counter
This counts the components of a document.

URI_COUNT

URL counter
In thid field, depending on URI, the number of field is entered. The individual URI parts are numbered.

URL
The length of this field is limited (4096 characters). If the URL does not fit into this field, the URL is divided and put into two fields. The counter URI_COUNT is increased by one.

Content table

In the table CONTENT, contents are directly transferred. Transfer is via an internal table. The relevant field is called LINE:

Data element: SDOK_SDATX

Data type: RAW

Length: 1022

Description: Line for binary document content, length for upload

Several components of various documents can be transferred in one content table: A new line is startedfor each component and the size of the individual components (table COMPONENTS) gives the start and end (line x) in the content table.

In the table ASCII_CONTENT contents are directly transferred. The transfer occurs via an internal table. The corresponding field is called LINE.

Data element: SDOK_SDAT

Data type: CHAR

Length: 1022

Description: Line for text document content, length for upload

Relations table

In the table RELATIONS relationships between documents are specified. The following attributes are provided for this:

DOC_COUNT

RELA_ID

Relations identification

Properties table

In the table PROPERTIES, the following two attributes are transferred:

PROP_NAME

Attribute name

PROP_VALUE

Attribute value

This table is used for methods that address only one document.

General functions

ASSIGN

This method allows the assignment of a document to another application object. The identification of the application object and the Document-ID of the document concerned are transferred.

CALL_NAVIGATOR

Identification of the application object (document set) is by the attributes described in the section 'Parameters'.

Documents are identified by the signature table (see section 'Tables').

In the table EXCLUDING you can specify which functions are not to be available. The following values are defined for EXCLUDING:

'NO_MODIFY'

No editing

'NO_DELETE'

No deleting

'NO_TRANSPORT'

No transporting

'NO_CREATE'

No creating

'NO_STANDARD_DOCS'

No standard document types

'NO_MODIFY_ATTRIS'

No changing of attributes/keywords

'NO_COPY'

No copying

'NO_USER_OPTIONS'

No user-specific settings

'NO_KEYWORDS'

No keywords

'NO_DOCINFO'

No document information

'NO_DISPLAY'

No displaying of documents

For example, it may be that you want it to be possible only to display documents in the BDN, meaning that you must explicitly exclude the functions for editing and deleting, in the table EXCLUDING.

CHANGE_PROPERTIES

This method is used to change or reset document attributes.

The application object (document set) is identified by the attributes described in the section 'Parameters'.Individual documents are specified by attributes that are also described in the section 'Parameters'. Attributes are changed in table PROPERTIES, which is described in the section 'Tables'.

DELETE

This method is used to delete documents.

The application object (document set) is identified by the attributes described in the section 'Parameters'.

In the signature table (see section 'Tables') you specify which documents are to be deleted. Since the object key is optional, everything can be deleted.

GET_FAST_INFO

This method does not return documents, but rather information about existing documents. This informationis stored in the signature table (see section 'Tables'). General information and attributes are storedin the signature table. Technical information about the individual components from which the documentsoriginate is stored in the component table. The application object (document set) is identified by the attributes described in the section 'parameters'.

In contrast to the method GET_INFO, the method GET_FAST_INFO does not deliver information about the components of the document or any detailed information about individual documents.

Depending on the value of the parameter GET_PROPERTIES, some (GET_PROPERTIES = 'X') or no document attributes are delivered.

GET_INFO

This method does not return a document, but instead information about existing documents. This informationis stored in the signature and component table (see section 'Tables'). General information and attributesare stored in the signature table. Technical information on the individual components is stored in the component table.

The application object (document set) is identified by the attributes described in the section 'Parameters'.

GET_INFO_NEWEST_ONLY

This method returns information on the most recent version of a document. Otherwise, it corresponds to the method GET_INFO.

QUERY_DOCUMENT

This method allows a flexible query about the attributes of a document.

The selection criteria are specified in the table 'QUERY'. Each entry imposes restrictions on an attribute similar to the structure of a 'Ranges' table.

COPY

This method is used to copy a document.

The application object (document set) is identified by the attributes described in the section 'Parameters'. The content version is identified by the attributes also described in the section 'Parameters'.

A document is copied and the link is also copied. The following attributes are used as transfer parameters:

NEW_CLASSNAME

Class name, name of application class

NEW_CLASSTYPE

Class type, type of application class

NEW_OBJKEY

Object key

NEW_CLIENT

Client
This parameter is optional, except for client-dependent documents, where it is mandatory.

In the table PROPERTIES, the attribute name and attribute value are transferred.

The new document is attached either to the outgoing business object or a new document. The new variant is specified by the following attributes, analogously to the identification of the content version.

NEW_DOC_ID,

Document identification

NEW_DOC_VER_NO

Document version number

NEW_DOC_VAR_ID

Document variant identification

This means that this method can be used for both copying and reassigning.

CREATE_WITH_FILES/_URL/_TABLES/AS_TABLE

The following four methods are available for creating documents:

CREATE_WITH_FILES

CREATE_WITH_TABLE

CREATE_WITH_AS_TABLE

CREATE_WITH_URL

The difference between these methods is the source from which the data is retrieved. The source can be a file name, a table or a URL.

The application object (document set) is identified by the attributes described in the section 'Parameters'.

The method CREATE_WITH_FILES is identified by the following additional parameters (see section 'Tables'):

FILES

SIGNATURE

The method CREATE_WITH_TABLE is identified by the following additional parameters (see section 'Tables'):

COMPONENTS

CONTENT

SIGNATURE

The method CREATE_WITH_AS_TABLE is identified by the following additional parameters:

COMPONENTS

ASCII_CONTENT

SIGNATURE

The method CREATE_WITH_URL is identified by the following additional parameters (see section 'Tables'):

COMPONENTS

URIS

SIGNATURE

note
CREATE_WITH_URL must always be called in conjunction with CONFIRM_CREATE so that a document can be identified as stored succcessfully.
For this method, only a target URL is transferred. CONFIRM_CREATE passes on the information that the document was stored successfully.

CREATE_WITH_OWN_URL

This method is a slight variation of the method CREATE_WITH_URL. The source URL is not simultaneouslygenerated in this case, but instead can be externally specified. This obviously pre-supposes that the contents of the document can be reached via this URL.

The source URL is transferred via the Parameter URL.

In the parameter MIMETYPE, the MIMETYPE of the document must be transferred.

The parameter BINARY_FLAG specifies whether the content of the Document is binary (BINARY_FLAG = 'X').

In this case it is not necessary to subsequently call the method CONFIRM_CREATE.

UPDATE_WITH_FILES/_URL/_TABLES

The following four methods are available for changing documents:

UPDATE_WITH_FILES

UPDATE_WITH_TABLE

UPDATE_WITH_AS_TABLE

UPDATE_WITH_URL

The difference between these four methods is the source from which the data is retrieved. The source can be a file name, a table or a URL. The table can be either an ASCII or a binary table.

The application object (document set) and the document are identified by the attributes described in the section 'Parameters'.

The method UPDATE_WITH_FILES is identified by the following additional parameters (see section 'Tables'):

FILES

SIGNATURE

The method UPDATE_WITH_TABLE is identified by the following additional parameters (see the section 'Tables'):

COMPONENTS

CONTENT

SIGNATURE

The method UPDATE_AS_WITH_TABLE is identified by the following additional parameters (see the section 'Tables'):

COMPONENTS

ASCII_CONTENT

SIGNATURE

The method UPDATE_WITH_URL is identified by the following additional parameters (see section 'Tables'):

COMPONENTS

URIS

SIGNATURE

Note
UPDATE_WITH_URL must always be called in conjunction with CONFIRM_UPDATE so that a document can be identified as successfully stored.
For this method, only a target URL is transferred. CONFIRM_UPDATE passes in the information that the document was changed successfully.

GET_WITH_FILES/_URL/_TABLE/AS_TABLE

These methods are used to return documents. Four different methods are available:

GET_WITH_FILES

GET_WITH_TABLE

GET_WITH_AS_TABLE

GET_WITH_URL

The difference between these four methods is the source from which the data is retrieved. The source can be either a file name, a table or a URL.

The application object (document set) is identified by attributes described in the section 'Parameters'.

The method GET_WITH_FILES is identified by the following additional parameters (see section 'Tables'):

FILES

The target directory is transferred in the table FILES.

SIGNATURE

During a call, this table is used to limit the number of hits. After the call, it is used for information.

The method GET_WITH_TABLE is identified by the following additional parameters (see section 'Tables'):

COMPONENTS

CONTENT

SIGNATURE

The method GET_WITH_AS_TABLE is identified by the following additional parameters (see section 'Tables'):

COMPONENTS

ASCII_CONTENT

SIGNATURE

The method GET_WITH_URL is identified by the following additional parameters (see section 'Tables'):

SIGNATURE

COMPONENTS

This table makes the entire content available.

URIS

This specifies only the URL that points to the document.

URL_LIFETIME

Time period for the validity of a URL, lifespan. This parameter can have two different meanings:

This parameter concerns only URIs in the SAP System. It specifies the lifespan for both the URL and the URL to which that URL points.
If the document content is in the R/3 database, URL_LIFETIME controls the lifetime of the table on the client.
For more information, see the documentation on the function module DP_CREATE_URL, in particular the documentation on the parameter LIFETIME.
If GET_WITH_URL returns a general URL on a content server, the lifetime can be calculated from the validity of the URL (two hours maximum). A digital signature must be used.

CONFIRM_CREATE

This method is always called in conjunction with CREATE_WITH_URL, CREATE_VARIANT_WITH_URL and CREATE_VERSION_WITH_URL.

It must always be called when storing via the URL was successful. If it was not successful, the administration data should be deleted using DELETE.

The application object (document set) is identified by the attributes described in the section 'Parameters'.

In addition, this method is specified by the following parameters:

COMPONENTS

URIS

SIGNATURE

CONFIRM_UPDATE

This method is called in conjunction with UPDATE_WITH_URL.

It must always be called if storing via the URL was successful. If it was not successful, the administration data should be deleted using DELETE.

The application object is identified (document set) by the attributes described in the section 'Parameters'.

In addition, this method is specified by the following parameters:

COMPONENTS

URIS

SIGNATURE

So this method is like method CONFIRM_CREATE, except that it concerns updating and not creating documents.

Special functions

Functions for relations

CREATE_RELATION

This method is used to create relationships for an application object.

The outgoing document is represented by the attributes described in the section 'Parameter'. The relationships specified in the table SIGNATURE are generated for this document and confirmed via the table RELATION.

GET_RELATIONS

This method is used to make the relationships existing for a document with the relevant partners, available.

The outgoing document is represented by the attributes described in the section 'Parameters'. TableRELATION contains the relationships existing for the document. The partner documents are specified in the table SIGNATURE.

DELETE_RELATIONS

This method is used to delete the existing relationships for a document.

The application object (document set) is identified by the attributes described in the section 'Parameters'. The existing relationships for this document, specified in the table RELATION, are deleted explicitly.

QUERY_RELATIONS

This method allows the attributes of a relationship, or the attributes of the documents to which therelationship is to exist, to be queried. Apart from the identification of the application object andthe document from which the relationships originate, the method has two additional transfer parameters,for the attributes of the required documents (Parameter SIGNATURE) and for the transfer of the search range of the required relationship attributes (Parameter QUERY).

The selection criteria are specified in the table 'QUERY'. Each entry imposes restrictions on the attribute analogous to the structure of a Ranges table.

Functions for versions and variants

CREATE_VARIANT_WITH_FILES/_TABLE/_AS_TABLE/_URL

There are four methods available for creating language and format variants:

CREATE_VARIANT_WITH_FILES

CREATE_VARIANT_WITH_TABLE

CREATE_VARIANT_WITH_AS_TABLE

CREATE_VARIANT_WITH_URL

The difference between the four methods - as with CREATE_WITH_FILES, CREATE_WITH_TABLE, CREATE_WITH_AS_TABLEand CREATE_WITH_URL - is the source from which the data is retrieved. The source can be a file name, a table or a URL.

The application object (document set) is identified by the attributes described in the section 'Parameters'. The variant is also identified by attributes described in the section 'Parameters'.

The new variant is identified by the following parameters:

NEW_DOC_VAR_ID

New variant ID

NEW_DOC_VAR_TG

New variant tag
The variant tag can take the following forms:

Original

Language variant

Format variant

One of these forms must be transferred when the method is called. The new variant ID is returned.

The parameter PROPERTIES is used in place of the parameter SIGNATURE (see section 'Tables').

The method CREATE_VARIANT_WITH_FILES is identified by the additional parameter FILES (see section 'Tables').

The method CREATE_VARIANT_WITH_TABLE is identified by the following additional parameters (see section 'Tables'):

COMPONENTS

CONTENT

The method CREATE_VARIANT_WITH_TABLE is identified by the following additional parameters (see section 'Tables'):

COMPONENTS

ASCII_CONTENT

The method CREATE_VARIANT_WITH_URL is identified by the following additional parameters (see section 'Tables'):

COMPONENTS

URIS

Note

CREATE_VARIANT_WITH_URL must always be called in conjunction with CONFIRM_CREATE so that a document can be identified as successfully stored.
For this method only one target URL is transferred. CONFIRM_CREATE passes on the information that the document was created successfully.

CREATE_VERSION_WITH_FILES/TABLE/URL

The following four methods are available for creating content versions:

CREATE_VERSION_WITH_FILES

CREATE_VERSION_WITH_TABLE

CREATE_VERSION_WITH_AS_TABLE

CREATE_VERSION_WITH_URL

The application object (document set) is identified by the attributes described in the section 'Parameters'. The version is also identified by attributes described in the section 'Parameters'.

The new variant is identified by the parameter NEW_DOC_VER_NO, that is, by the new version number.

The parameter PROPERTIES is used in place of the parameter SIGNATURE.

The method CREATE_VERSION_WITH_FILES is identified by the additional parameter FILES (see section 'Tables').

The method CREATE_VARIANT_WITH_TABLE is identified by the following additional parameters (see section 'Tables'):

COMPONENTS

CONTENT

The method CREATE_VARIANT_WITH_AS_TABLE is identified by the following additional parameters (see section 'Tables'):

COMPONENTS

ASCII_CONTENT

The method CREATE_VERSION_WITH_URL is identified by the following additional parameters (see section 'Tables'):

COMPONENTS

URIS

Note

CREATE_VERSION_WITH_URL must always be called in conjunction with CONFIRM_CREATE, so that a document can be identified as succesfully stored.
For this method only one target URL is transferred. CONFIRM_CREATE passes on the information that the document was stored succesfully.

Functions for the transport

GET_TRANSPORT_INFOS

This method is used to return the entries necessary for the transport.

The application object (document set) is identified by the attributes described in the section 'Parameters'.The document(s) is/are identified by the signature table, that is, by the parameter SIGNATURE (see section 'Tables').

The parameter COMMFILE_ENTRIES retrieves the necessary information for the transport, that is, the individual object entries for requests and tasks in the Workbench Organizer.

DOCUMENT_ENQUEUE

This method prevents other users from accessing a document. You can only implement one logical lock.The lock is only effective on a logical level. Use of the remaining methods is possible as before. Themethod DOCUMENT_ENQUEUE should always be implemented when it is possible that several people have accessto modify a document at the same time. If there is an error in calling this method, perhaps becausethe document is already locked by another user, you should avoid executing modifying methods because otherwise data consistency cannot be guaranteed.

After finishing the modifications you should call the method DOCUMENT_DEQUEUE, which will unlock the document.

DOCUMENT_DEQUEUE

This method unlocks a document which has previously been locked by the method DOCUMENT_ENQUEUE.

Integration of the class CL_BDS_DOCUMENT_SET.

The integration of BDS in SAP applications can be divided into three phases:

Analysis
Discussion and decision-making
Implementation

The individual phases are explained in more detail below:

1. Analysis

In the analysis phase general questions and the scope of the intended BDS integration into the relevant SAP application are specified:

What is the business background concerned?

For which release is the BDS to be integrated?

What types of document are to be stored?

Example: Bitmaps, Office documents

How many documents are there likely to be?

Does the SAP application need its own administration tables?

Which delivery class should the administration tables have?

What is the ID of the application class?

What type of application class is concerned?

Business Object Repository

R/3 Class Library

Others

Is a transport connection required?

Is the application context client-specific?

Which BDS methods is it intended to use?

Example: CALL_NAVIGATOR (calling the BDN) or CREATE_VARIANT_WITH_FILES (creating a variant and also transferring the file name).

Are special attributes required? If so, what?

2. Discussion and decision-making

In this phase you make contact with the BDS integration group. You discuss, together with the developmentgroup, how your requirements can best be met. You decide which data model to use and which methods to use for your application.

3. Implementation

You integrate the methods required for your application.

Application examples

The BDS can be integrated into all SAP applications that work with documents and that have no special requirements for document management.

An example application is Office -> Business Documents -> Documents -> Find.

Glossary

Business Document Navigator

BDN.
User interface of the Business Document Service.

Business Document Set

All documents for a given application object.

Desktop Office Integration

Document

The word document usually means an offical piece of writing. It is derived from the Latin word documentum= instruction/enlightenment on something, helpful, proof. This interpretation of document is based onthe conception of tangible, present written information usually on paper, parchment, micro film or another tangible medium.
Due to the digitalization of information, a document can also be any form of digitalized information, for example: visible or audible recordings of information.
In the context of a document management system, a document can be regarded in the context of its entirelife history, that is, as a sequence of differing content, language and format versions. In addition, context information and links for other objects and are considered.

MIME type

The MIME type specifies the format of a document. The MIME type is specified by the content-type and subtype.
MIME types are registered by the IANA (Internet Assigned Number Authority), frim which a list of "official"MIME types can be obtained. As well as the registered MIME Types, some unregistered ones are also used. These are distinguished from the registered MIME types by the syntax type/x-subtype (by the insertion x-).

Class

Definition of attributes, operations and semantics for a quantity of objects.

Class name

Unique name for class.

Class type

Name of type of class. The following types are currently defined:

Business Object Repository

Class Library

Other

Logical system

Instance of an SAP System

Object

An active unit, concretely existing in the current system. Each object is an example for a class.

Object key

Unique identification of an object.
Unique identification of an instance within the logical systemand the class. The SAP application can specify the object key. Alternatively, the BDS can generate the object type in the form of a GUID (only for the CREATE method).

Variant

Variants that are semantically equal to the content version, but present the same content in a different language or in a different technical format, can be derived from all content versions.

Version

Documents can have different statuses throughout their life cycle. The status of a document can be changesby content versioning. Content version is used here as a synonym of version. New versions require editing options.