This blog provides guidelines to help you create XML date rules in your SAP S/4HANA Cloud system. XML date rule is part of the configuration activities for date management in the application area Service of SAP S/4HANA Cloud. It originated from that in the SAP Customer Relationship Management (CRM). You can use it to define very customized date rules to control calculation of dates in service contracts for example.

In this blog, we will first give you an introduction about the XML date rules. Then there will be some detailed technical explanations, such as structure and expressions of XML date rules. We will also provide you some simple examples that use the expressions and give the test run results as well. At last, you can find some business use cases based on business scenarios of service contracts.

Business Value

The validity periods of service contracts and billing plan settlement start and end dates as well, are controlled by date management. SAP has provided a default set of date rules to set up service contract dates when you create a service contract. However, with the customized configurations, you can configure the date rules for the dates in your service contract per your own business requirement. For example, you can define the service contract start date and end date, define date rules for generation of billing plans.

Technical Details

XML Element and Attribute

XML (Extensible Markup Language) 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 an 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

Date Rule Structure

An XML document consists of only one element that contains the whole information which looks like:

<?xml version="1.0"?>
<TimeRule>
   <TimeRuleSource>
      <ruleline>
         <!-- Date Rule Expressions -->
      </ruleline>
   </TimeRuleSource>
</TimeRule>

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

An expression can have three kinds of return types:

Time Expression
Duration Expression
Time Object Reference Expression

Variable RESULT

If you don’t want to specify the result’s name in a date rule, you can use the name RESULT. After the evaluation of the rule, the variable holds the result. This variable does not need to be defined in a date profile. For each return type, the variable instance is created within the date 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.

Time Expressions (Total 9)

1 ConstTimeExp This expression defines a constant time point in a date rule.

XML Code

<!-- Use real timestamp -->
<ConstTimeExp timestamp="20221231235959">
   <!-- Time Object Reference Expression -->
   <VarObjectExp name=”SYSTEM”/>
</ConstTimeExp>
<!-- Use current date and time -->
<ConstTimeExp timestamp="now">
   <!-- Time Object Reference Expression -->
   <VarObjectExp name=”SYSTEM”/>
</ConstTimeExp>

· The parameter <Time Object Reference Object> is mandatory for this expression to determine the time zone.

· The attribute timestamp can be set in format “YYYYMMDDHHMMSS” with a specific timestamp, or use “now” to set the current timestamp to this attribute. The timestamp is always in the UTC time zone.

2 ConstLocTimeExp This expression defines a constant time point in a date rule with local date and time.

XML Code

<ConstLocTimeExp date="20221231" time="235959">
   <!-- Time Object Reference Expression -->
   <VarObjectExp name=”SYSTEM”/>
</ConstLocTimeExp>

· The parameter <Time Object Reference Object> is mandatory for this expression to determine the time zone.

· The attribute date can be set in format “YYYYMMDD” with a specific date, or use “now” to set the current date to this attribute.

· The attribute time can be set in format “HHMMSS” with a specific time, or use “now” to set the current time to this attribute.

3 VarTimeExp This expression defines a time variable.

XML Code

<VarTimeExp name="RESULT" position="F">
</VarTimeExp>

· The attribute name can be a pre-defined date type in the date profile, or “RESULT” as the default return value (See Variable RESULT).

· The attribute position can be “B” or “F” for beginning, or “E” or “T” for ending. As a time variable is consisted of two parts, it is necessary to specify this attribute.

4 MoveTimeExp This expression adds or subtracts a duration from a time point.

XML Code

<MoveTimeExp direction="+">
<!-- Time Expression -->
<VarTimeExp name="CONTSTART" position="F"/>
<!-- Duration Expression -->
<VarDuraExp name='PERIOD'/>
</MoveTimeExp>

· The parameter <Time Expression> defines a time point.

· The parameter <Duration Expression> defines a duration that will be added to or subtracted from the defined time point.

· The attribute direction can be set as “+” or “–” to add or subtract a certain duration based on a time point.

5 MoveToTimeExp This expression moves a time point to the n-th repetition from the start time. The start time is determined from the time expression as well as the time unit specified in the duration expression (See Time Unit).

XML Code

<MoveToTimeExp>
   <!-- Time Expression -->
   <VarTimeExp name="CONTSTART" position="F"/>
   <!-- Duration Expression -->
   <ConstDuraExp duration="360" timeunit="DAY">
      <VarObjectExp name=”SYSTEM”/>
   </ConstDuraExp>
</MoveToTimeExp>

· The parameter <Time Expression> defines a time point.

· The parameter <Duration Expression> defines a duration.

6 RoundTimeExp This expression rounds a time to the beginning or ending of a time unit.

XML Code

<RoundTimeExp timeunit="MONTH" position="B">
   <!-- Time Expression -->
   <VarTimeExp name="CONTSTART" position="B"/>
</RoundTimeExp>

· The parameter <Time Expression> defines a time point.

· The attribute timeunit defines a time unit to perform the rounding.

· The attribute position can be either “B” for beginning or “E” for ending.

7	*MinTimeExp*	This expression determines the minimum of two times.
	XML Code	`<MinTimeExp> <!-- Time Expression 1 --> <VarTimeExp name="TIME1"/> <!-- Time Expression 2 --> <VarTimeExp name="TIME2"/> </MinTimeExp>`
	· The parameters *<Time Expression 1>* and *<Time Expression 2>* define 2 time points.

8	*MaxTimeExp*	This expression determines the maximum of two times.
	XML Code	`<MaxTimeExp> <!-- Time Expression 1 --> <VarTimeExp name="TIME1"/> <!-- Time Expression 2 --> <VarTimeExp name="TIME2"/> </MaxTimeExp>`
	· The parameters *<Time Expression 1>* and *<Time Expression 2>* define 2 time points.

9 AssignTimeExp This expression assigns a time variable from source to target.

XML Code

<AssignTimeExp>
   <!-- Target Time Expression -->
   <VarTimeExp name="TARGET"/>
   <!-- Source Time Expression -->
   <VarTimeExp name="SOURCE"/>
</AssignTimeExp>

· The parameter <Source Time Expression> defines a source time point.

· The parameter <Target Time Expression> defines a target time point.

Duration Expressions (Total 4)

1 ConstDuraExp This expression defines a constant duration in a date rule.

XML Code

<ConstDuraExp duration="30" timeunit="DAY">
   <!-- Time Object Reference -->
   <VarObjectExp/>
</ConstDuraExp>

· The parameter <Time Object Reference> is mandatory for this expression to determine the time zone.

· The attribute duration specifies the value of the duration.

· The attribute timeunit specifies the time unit of the duration.

2	*VarDuraExp*	This expression defines a duration variable.
	XML Code	`<VarDuraExp name=”RESULT”> </VarDuraExp>`
	· The attribute *name* can be a pre-defined duration in the date profile, or “RESULT” as the default return value (See Variable RESULT).

3 DiffTimeExp This expression calculates the duration between two time points.

XML Code

<DiffTimeExp timeunit="WEEK">
   <!-- Time Expression 1 -->
   <VarTimeExp name="TIME1"/>
   <!-- Time Expression 2 -->
   <VarTimeExp name="TIME2"/>
   <!-- Time Object Reference -->
   <VarObjectExp/>
</DiffTimeExp>

· The parameters <Time Expression 1> and <Time Expression 2> defines 2 time points.

· The parameter <Time Object Reference> is mandatory for this expression to determine the time zone.

· The attribute timeunit defines the time unit of the duration result.

4 AssignDuraExp This expression assigns a duration variable from the source to target.

XML Code

<AssignDuraExp>
   <!-- Target Duration Expression -->
   <VarDuraExp name="TARGET"/>
   <!-- Source Duration Expression -->
   <VarDuraExp name="SOURCE"/>
</AssignDuraExp>

· The parameter <Source Duration Expression> defines a source duration.

· The parameter <Target Duration Expression> defines a target duration.

Reference Object Expressions (Total 2)

1	*ConstObjectExp*	This expression defines a constant reference object in a date rule.
	XML Code	`<ConstObjectExp calid=”01” tstreamid=””> </ConstObjectExp>`

2	*VarObjectExp*	This expression defines a reference object in a date rule.
	XML Code	`<VarObjectExp name=”SYSTEM”> </VarObjectExp>`
	· The attribute *name* can be a pre-defined reference object in the date profile.

Time Units

Time Unit	Description	For MoveToTimeExp
*SECOND*	Second	· Start time: minute (DD/MM/YYYY HH:MM:00) · Value range: 0..59
*MINUTE*	Minute	· Start time: minute (DD/MM/YYYY HH:00:00) · Value range: 0..59
*HOUR*	Hour	· Start time: minute (DD/MM/YYYY 00:00:00) · Value range: 0..23
*DAY*	Day	· Start time: year (01/01/YYYY HH:MM:SS) · Value range: 1..365
*WEEK*	Week	· Start time: year (01/01/YYYY HH:MM:SS) · Value range: 1..52
*MONTH*	Month	· Start time: year (01/01/YYYY HH:MM:SS) · Value range: 1..12
*QUARTER*	Quarter	· Start time: year (01/01/YYYY HH:MM:SS) · Value range: 1..4
*YEAR*	Year	· Start time: year (01/01/0000 HH:MM:SS) · Value range: 1..9999
*EXACT*	Exact time without expansion	· Do not support

Examples

We provide 4 examples and test run results to demonstrate the expressions that have been introduced above.

Get current date and time

XML Date Rule

<?xml version="1.0"?>
<TimeRule>
    <TimeRuleSource>
        <ruleline>
            <AssignTimeExp>
                <VarTimeExp name="RESULT" position="F"/>
                <ConstTimeExp timestamp="now">
                    <VarObjectExp name=”SYSTEM”/>
                </ConstTimeExp>
            </AssignTimeExp>
        </ruleline>
    </TimeRuleSource>
</TimeRule>

Test Result

Determine the duration between two time points

XML Date Rule

<?xml version="1.0"?>
<TimeRule>
   <TimeRuleSource>
      <ruleline>
         <AssignDuraExp>
            <VarDuraExp name="RESULT"/>
            <DiffTimeExp timeunit="DAY">
               <ConstTimeExp timestamp="20220101000000">
                  <VarObjectExp name="SYSTEM"/>
               </ConstTimeExp>
               <ConstTimeExp timestamp="now">
                  <VarObjectExp name="SYSTEM"/>
               </ConstTimeExp>
               <VarObjectExp/>
            </DiffTimeExp>
         </AssignDuraExp>
      </ruleline>
    </TimeRuleSource>
</TimeRule>

Test Result

Get last day of month

XML Date Rule

<?xml version="1.0"?>
<TimeRule>
   <TimeRuleSource>
      <ruleline>
         <AssignTimeExp>
            <VarTimeExp name="RESULT" position="F"/>
            <MoveTimeExp direction="-">
               <RoundTimeExp timeunit="MONTH" position="E">
                  <ConstTimeExp timestamp="20220804000000">
                     <VarObjectExp name="SYSTEM"/>
                  </ConstTimeExp>
               </RoundTimeExp>
               <ConstDuraExp duration="1" timeunit="SECOND">
                  <VarObjectExp name="SYSTEM"/>
               </ConstDuraExp>
            </MoveTimeExp>
         </AssignTimeExp>
      </ruleline>
   </TimeRuleSource>
</TimeRule>

Test Result

Get 15^th of month

XML Date Rule

<?xml version="1.0"?>
<TimeRule>
   <TimeRuleSource>
      <ruleline>
         <AssignTimeExp>
            <VarTimeExp name="RESULT" position="F"/>
            <MoveTimeExp direction="+">
               <RoundTimeExp timeunit="MONTH" position="B">
                  <ConstTimeExp timestamp="20220804000000">
                     <VarObjectExp name="SYSTEM"/>
                  </ConstTimeExp>
               </RoundTimeExp>
               <ConstDuraExp duration="14" timeunit="DAY">
                  <VarObjectExp name="SYSTEM"/>
               </ConstDuraExp>
            </MoveTimeExp>
         </AssignTimeExp>
      </ruleline>
   </TimeRuleSource>
</TimeRule>

Test Result

Business Use Cases

Service contract start date and end date

When creating a service contract, the start date and end date are determined automatically.

The service contract start date is set to current date by using the date rule TODAY (Today’s Date).
The service contract end date is determined with date rule CONT001 (Contract Begin + Validity Period) which is 1 year after service contract start date as default.

Service Contract Start/End Date

Date Rules

Now let’s create 2 new XML date rules for service contract start/end date and then assign them to the date profile. With the new date rules, for instance, we can set the dates as:

Service contract start date: 1^st of the current month
Service contract end date: 3 years after service contract start date

The service contract start/end date can be redetermined when the date rule is changed.

Service Contract Start/End Date

Date Rules

Periodic billing plan

In service contract, the date rule is also used for periodic billing plan creation. When creating a service contract item, the billing plan is generated on a monthly basis by default.

It is also possible to change the default Settlement Period Rule to the customized one. This can be much more flexible for customer to define how the billing plan looks like.

In this example, we are going to define a date rule based on natural quarter. It means the first billing request line will end at the last day of the current quarter, and the second billing request line will start at the first day of next quarter.

	*Service Contract Item Billing Plan*
	*Date Rules*

Additional Information

For more information about a complete configuration process, see this blog How to Use Date Management to Configure Service Contract Dates.

Conclusion

In this blog, you have learnt how you can create your own date rules and enable them in your SAP S/4 HANA Cloud system. If you have any questions, please comment under this blog. We will get back to you soon with our answers. If you have any other questions about service contracts, you can find Q&A and post your questions in the community.

Tags: SAP S/4HANA Cloud SAP S/4HANA Cloud for Sales SAP S/4HANA Cloud for Service

Sara Sampaio

Author Since: March 10, 2022

0 0 votes

Article Rating

0 Comments

Inline Feedbacks

View all comments

Business Value

Technical Details

XML Element and Attribute

Date Rule Structure

Variable RESULT

Time Expressions (Total 9)

Duration Expressions (Total 4)

Reference Object Expressions (Total 2)

Time Units

Examples

Get current date and time

Determine the duration between two time points

Get last day of month

Get 15^th of month

Business Use Cases

Service contract start date and end date

Periodic billing plan

Additional Information

Conclusion

Sara Sampaio

Company

Explore More

Business Value

Technical Details

XML Element and Attribute

Date Rule Structure

Variable RESULT

Time Expressions (Total 9)

Duration Expressions (Total 4)

Reference Object Expressions (Total 2)

Time Units

Examples

Get current date and time

Determine the duration between two time points

Get last day of month

Get 15th of month

Business Use Cases

Service contract start date and end date

Periodic billing plan

Additional Information

Conclusion

Sara Sampaio

Get 15^th of month