Skip to end of metadata
Go to start of metadata

Purpose

You are creating date rule in CRM system, the date rule is created using XML and this document provides guidelines for creating the XML date rules.

Overview

You can create date rules in Customizing according to your requirements. You make the required settings in Customizing for CRM -> Basic Functions -> Date Management -> Define Date Types, Duration Types and Date Rules. There is a rule editor available for this, in which you can define several rules using XML rule.

Extensible Markup Language (XML) defines a set of rules for encoding documents in a format that is both human-readable and machine-readable. It is a textual data format with strong support via Unicode for the programming languages of the world. Although the design of XML focuses on documents, it is widely used for the representation of arbitrary data structures, for example in services. Please note that XML is not an SAP provided feature that is used for encoding documents. It is a markup language and is an additional feature where in XML documents consisting entirely of characters from the Unicode repertoire. Except for a small number of specifically excluded control characters, any character defined by Unicode may appear within the content of an XML document.

XML includes facilities for identifying the encoding of the Unicode characters that make up the document, and for expressing characters that, for one reason or another, cannot be used directly.Kindly note that the following is to be used as a guideline and is not a sap specific documentation. Please use it as a reference. ”

Technical Details

Some of the examples in this documentation seem very complex, even for "simple" time rules such as getting the last working day of a week (see Examples).

Introduction into XML:To begin, here are some basic rules of XML:

XML documents use a self-describing and simple to use syntax.

  1. All XML elements must have a closing tag. With XML, it is illegal to omit the closing tag.
  2. XML tags are case sensitive.
  3. All XML elements must be properly nested. Improper nesting of tags makes no sense to XML.
  4. All XML documents must have a root element. In other words, all XML documents must contain a single tag pair to define a root element.
  5. Attribute values must always be quoted. With XML, it is illegal to omit quotation marks around attribute values.
  6. XML parsers preserve all whitespace in XML documents, even that which is considered non-significant.
  7. The use of the ampersand [&] symbol is reserved. XML uses this to define an entity reference.

XML Elements and Attributes

XML is designed to hold any kind of information. This information is stored in Elements. Elements are the basic building blocks of XML and are represented in a XML document as tag pairs. Attributes provide a mechanism to further define or classify an element. Elements have relationships with other elements in a document. Some are parents and some are children. Using this semantic description, one can see that children elements need parent elements defined and used first. As mentioned in the last section, an XML document must have a root element. Think of this as the ultimate parent element. The root element must be defined and used before all other elements and all sub-elements (children). All elements and sub-elements will reside inside of the root element. An element can have parsed content, mixed content, simple content, empty content or attributes in their definition.

XML elements must follow these naming rules:

  • Names can contain letters, numbers, and other characters
  • Names must not start with a number or punctuation character
  • Names must not start with the letters xml (or XML or Xml ...)
  • Names cannot contain spaces

A time rule starts with the declaration of your XML version and the markup .  

<?xml version="1.0"?>

<TimeRule>

 </TimeRule> 

This is the smallest valid time rule. It does absolutely nothing, but it is a correct XML time rule.

In XML, you can distinguish between well-formed and correct documents. Well-formed implies that the XML syntax is correct, but it doesn't say anything about the content. A valid document additionally fulfills the requirements of a document type definition (DTD).
SAP also delivers a DTD for time rules. Markups must have opening and closing tags, whereby the closing tag has the same name as the opening tag with a slash (/) at the beginning. Between these tags you find the content, which can consist of other markups or text.

<?xml version="1.0"?>

<TimeRule>

 <TimeRuleSource>
<! - begin of Rule source ->   

             </TimeRuleSource>

</TimeRule>

You can also enter white spaces or comments (<! -- comment -->) to get a more readable source code.

...

             <VarTimeExp displayType="VarTime" position="B"/>

                          <! -Variable: Time->

...

If a markup doesn't have content, you can save the closing tag by including the slash (/) at the end of the opening tag.The fields inside the opening tag are called attributes. Remember, there is no space between the attribute name, the equal sign, and the value.

One markup with its content is called an element.XML is case-sensitive.The structure of an XML document can be displayed as a tree, which is called document object model (DOM).

Structure of Time Rules:

An XML document consists of only one element that contains the whole information.

<TimeRule>

            <TimeRuleSource>

                      <RuleLine>

The Time Rule covers all the information about a time rule. At the moment, this is only the source code, but you can also include Meta data, which you can add in the future without interfering with existing time rules and coding.

Time rules are built from expressions that can return a value. With this technique it is possible to create complex expressions by simply cascading the expressions. However, we also need line organization to keep the XML source more readable. No-one would write a C program in only one line, even if it were possible. Also, we will use this XML representation to exchange time rules with other systems. Therefore we need to store Meta data in the DOM.

An expression can have three kinds of return types:

  • Time Expression
  • Duration Expression
  • Time Object Reference Expression

For further information about these three types, refer to the specification and design paper for time rules and time framework.As in most other programming languages, it is important that the types be chosen correctly. Otherwise the interpreter will send a syntax error instead of the result. A type cast is not supported because you cannot convert a time into duration.An expression is represented by one element. If this expression works on other expressions, these are also defined as elements. 

Example:  MinTimeExp(TimeExp1, TimeExp2) à TimeExp1 and TimeExp2 can be any element that belongs to the category time expression.

All other information, like names, directions or positions is specified via attributes.The attribute display, which is allowed in all elements, is optional and is used by the editor. With this information it is possible to display a sequence of expressions as a single command.Each line of a time rule can be seen as a tree consisting of nodes that represent the expressions. All these trees are organized as a list of lines at the node <TimeRuleSource>, which is part of the whole XML tree (DOM).

 Variable RESULT:

If you don't want to specify the result's name in a time rule, you can use the name RESULT. After the evaluation of the rule, this variable holds the result. However, this variable doesn't need to be defined in a profile nor in the time customizing for being used in a time rule. For each return type (see chapter 4), the variable instance is created within the time rule if it is not already in the context. This instance is then moved into the context, so that the calling application can access it.With this technique it is possible to create a rule that can be used to set multiple dates, e.g. TODAY

 Defination of Time expressions:

No

Time expressions

XML Code

Description

1

ConstTimeExp

<ConstTimeExp  displayname=“ConstTimeExp“             
                       timestamp=“20000716120000“        
                        timeunit=“DAY“>
   -> Time Object Reference Exp
</ConstTimeExp>

Defines a constant point in time in a time rule. A time stamp is entered in the internal format: YYYYMMDDHHMMSS, which is always in the UTC time zone.

 

ConstTimeExp

<ConstTimeExp      displayname=“ConstTimeExp“   
                              timestamp=“now“          
                             timeunit=“DAY“>
 -> Time Object Reference Exp
</ConstTimeExp>

To get the current time stamp, simply assign "now" to the timestamp attribute.

2

ConstLocTimeExp

<ConstLocTimeExp    displaytype="ConstLocTime   
                        date="20000301"                              
                         time="120000"                         
                          timeunit="DAY">
 -> Time Object Reference Exp
</ConstLocTimeExp>

Works like ConstTimeExp, but with local date and time. To get the current date and time, simply assign "now" to the date or time attribute. The default values of the profile can also be accessed by assigning "default" to the date or time. The default for the reference object in the profile is not supported.

3

VarTimeExp

<VarTimeExp     displayname=“VarTimeExp“  
             name=“RESULT“                                            
            position='F'/>

Get the value of a time variable from the context. The context can call back into the application if this variable is not already defined.  Since time variables are dates that consist of two points in times, it is necessary to specify this. Therefore, the attribute position is used. This can either be 'F' or 'B' for the beginning point in time (FROM) and 'T' or 'E' for the end point in time (TO).

 

 

 

 

4

MoveTimeExp

<MoveTimeExp  displayname=“MoveTimeExp“                                                    
                        direction=“+“>
 -> Time Expression
->Duration Expression
</MoveTimeExp>

MoveTimeExp can add (subtract) duration to (from) a time. The direction is specified with a "+" or a "-".  Certain kinds of durations need to work on a local date, e.g., if a factory calendar is needed. Therefore the reference object of the duration is used. The reference of the time has no relevance in this case.

5

MoveToTimeExp

<MoveToTimeExp displaytype="MoveToTime">
 -> Time Expression
->Duration Expression
</MoveToTimeExp>

Move to the n-th repetition of a time unit. See: Table 1 Time Units.

6

RoundTimeExp

<RoundTimeExp displaytype="RoundTimeExp"   
                            timeunit="DAY"                         
                          position="B">
 ->Time Expression
 </RoundTimeExp>

Round to the begin or end of a time unit, starting from one point in time. The reference object of time is needed to determine the time zone, which is important for time units that are local, e.g. day or week. The position can either be 'B' for begin or 'E' for end.Time units describe an interval, where the beginning point is included and the ending point is excluded.  When you round to the end of a day, you will get the following day:  00:00:00.

7

MinTimeExp

<MinTimeExp displaytype="MinTime"
> ->Time Expression
 ->Time Expression
</MinTimeExp>

Determines the minimum of two times. This comparison is based on the intervals that can be detemined from the time units of each time.For further details look at the chapter about time units.(6.4 Time Units)

8

MaxTimeExp

<MaxTimeExp displaytype="MaxTime">
 -> Time Expression
-> Time Expression
</MaxTimeExp>

Determines the minimum of two times. This compare is based on the intervals that can be determined from the time units of each time.For further details, refer to the chapter on time units. (6.4 Time Units) .

 Defination of Duration Expressions:

No

Duration Expressions

XML Code

Description

1

VarDuraExp

<VarDuraExp displaytype="VarDura"/>

Get the value of a duration variable from the context. The context can call back into the application if this variable is not already defined.

2

ConstDuraExp

<ConstDuraExp displaytype="ConstDura" duration="100" timeunit="DAY">
->Time Object Reference
</ConstDuraExp>

Define a constant duration in a time rule.

3

DiffTimeExp

<DiffTimeExp timeunit="WEEK">
-> Time Expression
-> Time Expression
-> Time Object Reference
</DiffTimeExp>

Calculate the duration between two times. The reference object defines the time zone and the calendar.

Defination of  Reference Object Expressions:

No

Reference object Expressions

XML Code

Description

1

VarObjectExp

<VarObjectExp displaytype="VarObject"/>

Get the value of a reference object variable from the context. The context can call back into the application if this variable is not already defined.The reference objects named "USER" and "SYSTEM" are available as default values.

2

ConstObjectExp

<ConstObjectExp  displaytype="ConstObject" calid="01"  tstreamid=""/>

Define a constant reference object in a time rule.
A reference object provides a time zone and a calendar. The calendar is of the internal type cl_timecalendar and consists of a day-based and a second-based calendar.  The day-based calendar is the factory calendar. For calculations that need to be precise, the second-based calendar, that is the time stream, is used. As it is not quite clear what the time stream identifier will be in future, this feature is not implemented yet. 

Time Units

Time units are used:

  • For time comparisons
  • To add (subtract) a duration to (from) a time.

                                                                                                        Table 1 Time Units

 Examples:Below are few examples for the XML code

No

Example

XML code

Description

1

A simple copy of a date

<xmlversion="1.0"?>
<TimeRule>
 <TimeRuleSource>
  <ruleline>
    <AssignTimeExp>
        <VarTimeExp position="F"/>
        <VarTimeExp position="F"/>
    </AssignTimeExp>
  </ruleline>
  <ruleline>
    <AssignTimeExp>
        <VarTimeExp position="T"/>
        <VarTimeExp position="T"/>
    </AssignTimeExp>
  </ruleline> 
 </TimeRuleSource>
</TimeRule>

 

2

Get current date

<?xml version="1.0"?>
<TimeRule>
   <TimeRuleSource>
   <! - Begin of Ruletree ->
      <ruleline>
      <! - Begin of new LINE ->         <AssignTimeExp      displaytype="AssignTime">
         <! - assign time- >        
    <VarTimeExp displayType="VarTime"
                        name="RESULT"
                        position="B">
            <! - variable: time ->
          </VarTimeExp>
            <ConstTimeExp displaytype="ConstTime"
                          timestamp="now"
                          timeunit="DAY">
            <!  - constant :Time ->
               <VarObjectExp displaytype="VarObject"/>
               <! - Variable:Timeobject ->
            </ConstTimeExp>
         </AssignTimeExp>
      </ruleline>

   </TimeRuleSource>
</TimeRule>

 

3

Determine the duration between two times

<ruleline>          <AssignDuraExp>
              <VarDuraExp/>
              <DiffTimeExp timeunit="DAY">
                  <VarTimeExp position="T"/>
                  <VarTimeExp position="F"/>
                  <VarObjectExp/>
              </DiffTimeExp>
          </AssignDuraExp>
      </ruleline>

 

4

From first until last working day in one week

<?xml version="1.0"?>
<TimeRule>
 <TimeRuleSource>
  <ruleline>    <! - First woeking day of week--->
    <AssignTimeExp>
        <VarTimeExp position="F"/>
        <MoveTimeExp direction="+">
          <RoundTimeExp timeunit="WEEK" position="B">
            <ConstLocTimeExp date="now"
                             time="120000" timeunit="DAY">
             <VarObjectExp/>
            </ConstLocTimeExp>
          </RoundTimeExp>
          <ConstDuraExp duration="0" timeunit="DAY">
            <VarObjectExp/>
          </ConstDuraExp>
        </MoveTimeExp>
    </AssignTimeExp>
  </ruleline>

  <ruleline>    <! - last working day of week ->
    <AssignTimeExp>
        <VarTimeExp position="T"/>
        <RoundTimeExp timeunit="DAY" position="E">
          <MoveTimeExp direction="-">
           <MoveTimeExp direction="-">                <RoundTimeExp       timeunit="WEEK" position="E">
                 <VarTimeExp position="F"/>
               </RoundTimeExp>
               <ConstDuraExp duration="1" timeunit="DAY">
                   <VarObjectExp/>
               </ConstDuraExp>
            </MoveTimeExp>
            <ConstDuraExp duration="0" timeunit="DAY">
                <VarObjectExp/>
            </ConstDuraExp>
          </MoveTimeExp>
        </RoundTimeExp>
    </AssignTimeExp>
  </ruleline>
 </TimeRuleSource>
</TimeRule>

To get the last working day, round to the end of the week, which is the first day of the following week: 00:00:00? Then move one day backwards without any calendar to make sure that you are in the previous week again. Now you can synchronize to the factory calendar by moving 0 days backwards with the time object that represents this calendar. After that, you are on the last working day at 00:00:00. If you need the whole day, round to the end of it. Otherwise you can add an amount of hours to get the time you want.

  Customizing:

 Below are the details to customize date rule in SPRO

 Time Rule Editor


Figure 8‑1 Modifying time rules within the TIMECUST transaction

You start creating or editing time rules in the TIMECUST transaction or in the IMG entry date management ???. In the Time Rules view (Figure 8‑1 Modifying time rules within the TIMECUST transaction You start creating or editing time rules in the TIMECUST transaction or in the IMG entry date management ???. In the Time Rules view (Figure 8‑1 Modifying time rules within the TIMECUST transaction

Figure 8‑1 Modifying time rules within the TIMECUST transaction ) you can create a new time rule and modify the description. Deleting an entry here only removes the customizing entry and does not affect the time rule. For removing time rules, please use p_timerule_delete program.Double-clicking on a time rule (or F2 - detail) calls up the version management (Figure 8‑2 Version management of time rules). The version number is dynamically determined from the sorted change time. A name 'Standard' in the version column marks the time rule that will be used if only the name is given - namely the default time rule. In the version management you are able to insert a time rule directly into a transport request. Because of the delivery types of the tables you need a workbench request.To open the XML editor, simply perform a double-click on one of the versions.

The main component of this editor is a text control that lets you enter the XML source of the time rule. In the toolbar or the menu you will find commands for syntax check, testing and copying the rule. 

 

 Figure 8‑2 Version management of time rules

When testing a time rule, the test frame requests all missing variables from the user. If one value is missing, the time rule may not be evaluated correctly. When entering a reference object only the time zone is needed, factory calendar and time stream are optional.
Figure 8‑3 XML time rule edito


Figure 8‑4 Input dialog for time profile


Figure 8‑5 Input dialog for reference object

Conclusion

Please note that XML is not an SAP provided feature that is used for encoding documents. The above details provide an idea for creating the XML rule for the date rules.

Related Contents

Related Documents

3 Comments

  1. Pretty good wiki, thanks!

  2. Former Member

    Excellent starting point

  3. So great one WIKI.

    Many thanks.