Liquid Studio 2021
Data Mapping / Data Mapper Functions / By Category / Date Time / Month
In This Topic
    Month
    In This Topic

    Function Name
    Month
    Category
    DateTime
    Icon
    Month
    Description
    Retrieve the month portion of a DateTime value
    Inputs
    DateTime DateTime value to retrieve month from
    Outputs
    Month Month value from DateTime input
    Properties
    None -

    Usage

    The Data Mapper DateTime Month function returns the month portion of a DateTime value. Many applications use DateTime values to record information about events, for example retail or other account transactions. It is often necessary to retrieve particular portions of a DateTime value, such as the month, or to separate the DateTime into its component parts for the target application. To apply the DateTime Month function, use the following process:

    Create a new Data Mapper file, dragging your XML data source and targets into the editor area. For this example we are using sales_source.xsd, an XML Schema Definition inferred from the following source:

    Source XML
    Copy Code
    <sales>
     <purchase>
      <sale_id>9099879823</sale_id>
      <item_ref>ab65gh7hh7</item_ref>
      <customer_id>34522</customer_id>
      <transaction>2003-01-20T07:15:32.42</transaction>
     </purchase>
     <purchase>
      <sale_id>2390865748</sale_id>
      <item_ref>g7hy65tfd3</item_ref>
      <customer_id>12009</customer_id>
      <transaction>2007-06-12T23:35:10.09</transaction>
     </purchase>
     <purchase>
      <sale_id>8250987123</sale_id>
      <item_ref>d4rf54r0op</item_ref>
      <customer_id>28769</customer_id>
      <transaction>2006-11-27T17:20:09.88</transaction>
     </purchase>
    </sales>
    

    For our target schema we will be using sales_target.xsd, inferred from the following XML:

    Target XML
    Copy Code
    <transactions>
     <sale id="8987612312" item="y6yt5i93e4">
      <cust_id>14398</cust_id>
      <bought_time>8</bought_time>
     </sale>
     <sale id="2090176549" item="i8u7b45f7y">
      <cust_id>23112</cust_id>
      <bought_time>11</bought_time>
     </sale>
     <sale id="2819283722" item="y6yt5i93e4">
      <cust_id>34309</cust_id>
      <bought_time>9</bought_time>
     </sale>
    </transactions>
    

    The data models retail transactions, including the DateTime for when a sale was made. Let's assume that in this case we only want to map the month during which each transaction took place, perhaps for marketing purposes. Here is the Data Mapper with Source and Target imported:

    Data Mapper Source and Target

    Drag the DateTime Month function from the Component Palette into the mapping area:

    Month Component

    Month Transform Added

    The Month function takes a single input, the DateTime in question, giving an output comprising the month portion. The input should be connected to the source item, which will normally be an item in the XML Reader. The output should be connected to the target item, whether an item in the XML Writer or another component in the Mapper, for example if you plan on using the Month value to sort or filter the data in terms of purchases made at different times of year.

    Connect the Month function input to the "transaction" output in the XML Reader and the Month output to the "bought_time" input in the XML Writer.

    Month Mapped

    Now the only portion of the DateTime mapped will be the month value. If you want to map more than one part of a DateTime, you can use the other DateTime functions, connecting them each to your source DateTime input and mapping them forward as necessary.

    Finally, connect the remaining inputs and outputs:

    Input and Output Connections Mapped

    We can now execute the transform by pressing Shift-F5 or the Execute button (Execute). The transform is applied and the file we selected as output opens in the editor:

    Output XML
    Copy Code
    <transactions>
     <sale id="9099879823" item="ab65gh7hh7">
      <cust_id>34522</cust_id>
      <bought_time>1</bought_time>
     </sale>
     <sale id="2390865748" item="g7hy65tfd3">
      <cust_id>12009</cust_id>
      <bought_time>6</bought_time>
     </sale>
     <sale id="8250987123" item="d4rf54r0op">
      <cust_id>28769</cust_id>
      <bought_time>11</bought_time>
     </sale>
    </transactions>
    

    The "bought_time" contains an indicator of the month during which each transaction was made, represented as a number between 1 and 12.

    If you pass a value to the Month function that is not a DateTime, the Mapper will attempt to parse it. If you pass the Month function a DateTime value which does not contain a month portion, the function will output a value of 1 by default.

    This is a scalar function so the standard rules apply if multiple values are presented to one or more inputs.

    See Also