Sign in
< Back to CIC Studio Top

Variables

Variables supply rules (and rule conditions) with values for their Inputs and Outputs parameters. A variable can hold system-generated information that is likely to change at runtime; it can also hold a user-defined initial value (in effect, making it a constant) – but that value too may change, if desired, at runtime.

Variables can be used like any other data node. For example, they can be used to:
  • provide source data or hold target data in the Properties view's Inputs and Outputs areas.
  • hold a formula result, and then as a parameter to perform a second calculation.
  • hard-code an initial value into a document.
Note: Hard-coding an initial value in a Rule is somewhat like using a "constant," but there are no true constants in the CIC Studio. An initial value defined in one Rule can still be overwritten if a later Rule affects the same node.

Variables can also be used as source or target values.

Variable panel

The Variables panel presents displays that can be used to populate rule properties. Variables contain data that does not appear in your local data files or incoming documents. From this panel you can add, edit, delete, expand or collapse variables. Existing Ruleset Data Objects (RDO) can also be added to the list of available parameters.

The panel contains different folders:
  • sys (System): Contains variables that capture Studio program information, such as Collection List, Current Source Element, and Current date and time. There are powerful Actions and Variables, including DateTime, List, and Duration types.
  • glb (Global): Contains variables that you create within the Ruleset as well as any Ruleset Data Objects (which also contain variables).
  • env (Environment): Contains variables specific to the document syntax of the source Schema. For example, a Ruleset using an EDI Schema as its source contains variables such as Acknowledgement ID, Sender ID, and Version Release. 

    User Reference fields: There are five User Reference fields available, which can be used to add custom fields to your Ruleset. One important example is using these fields (for Cloud integrations) to pass data from the Cleo Cockpit Projects (CCP) to the Integration Server so that data can make its way to the CIC Cockpit.

Creating Custom Variables

To create a custom (on-the-fly) variable, just click the Add Variable button and define the values (making sure nothing is already selected in the Variables panel). 

String-type Variables

String-type variables can be used to populate rule properties with character data that does not appear in local data files or incoming documents.

This process takes place in a Ruleset editor, in the Variables section.
  1. Make sure nothing in Variables is selected. If something is selected, Ctrl+click on it to deselect it.
  2. Click the Add Variable button to produce the Create a New Variable window.
    1. In the Name field, type what you'd like to call the variable.
    2. Select String from the Type drop-down.
    3. If you want to hard-code a value, type it in the Value field.
    4. If you wish to set an empty string (removing some characters is a common use case), then select the Initialize as empty string checkbox.
    5. (Version 1 Rulesets only) If you want to limit how long the data string can be, select the Set String Constraints check box. Type the maximum length in the Length field.
  3. Click OK to complete this task.
Use the new variable as you would any other child node from the source or target Schema.

Number Variables

Number-type variables can be used to populate rule properties with numeric data that does not appear in local data files or incoming documents.

This process takes place in a Ruleset editor, in the Variables section.
  1. Make sure nothing in Variables is selected. If something is selected, Ctrl+click on it to deselect it.
  2. Click the Add Variable button to produce the Create a New Variable window.
    1. In the Name field, type what you'd like to call the variable.
    2. Select Number from the Type drop-down.
    3. If you want to hard-code a value, type it in the Value field.
    4. If you want to limit the number of digits in the number, select the Set Numeric Constraints check box. Type the maximum length in the Total Digits field and how many decimal places should appear in the Decimal Precision field. This works in version 1 Rulesets only.
  3. Click OK to complete this task.
Next: Use the new variable as you would any other child node from the source or target Schema.

Boolean Variables

Boolean-type variables can be created with an initial true or false value, or to be populated later with a true or false value from a rule. Boolean-type variables are used mainly when customizing a Rule's condition.

This process takes place in a Ruleset editor, in the Variables section.
  1. Make sure nothing in Variables is selected. If something is selected, Ctrl+click on it to deselect it.
  2. Click the Add Variable button to produce the Create a New Variable window.
    1. In the Name field, type what you'd like to call the variable.
    2. Select Boolean from the Type drop-down.
    3. Choose a Value radio-button. Options are:
      • True - If the statement is true
      • False - If the statement is false
      • Reset - Reset the values
      Note: Clicking true or false creates a hard-coded constant value. Because it is a hard-coded constant value, if you want to change it, you must reset the value first. The Reset button only works after you've defined and saved this variable once.
  3. Click OK to complete this task.
Next: Use the new variable when applying conditions to rules in the Properties view's Conditions panel in a Ruleset editor.

Object Variables

Object-type variables can be used to populate rule properties with data that does not appear in local data files or incoming documents. Use an object-type variable when you do not know what type of data (string, number, etc.) will populate the variable.

This process takes place in a Ruleset editor, in the Variables section.
  1. Make sure nothing in Variables is selected. If something is selected, Ctrl+click on it to deselect it.
  2. Click the Add Variable button to produce the Create a New Variable window.
    1. In the Name field, type what you'd like to call the variable.
    2. Select Object from the Type drop-down.
  3. Click OK to complete this task.
Next: Use the new variable as you would any other child node from the source or target Schema.

DateTime Variables

The DateTime variable type holds the representation of a date and/or time in the format of the number of milliseconds since January 1, 1970. This variable type is currently supported in the new transformation engine only.

You can safely manipulate date-time values in your data without the need for manual editing or custom rules to do so.

The Move rule (version 2) automatically converts the date into DateTime format (for EDI and Database).

In conjunction with this variable type, several Ruleset Actions are available. This table lists Actions that support the DateTime variable type.

 
Action Description
AddDateTime Adds two DateTime types and returns a new DateTime value.
AddDateTimeWithFields Adds specified values to a DateTime and returns a new DateTime value.
CreateDateTime Creates a DateTime.
CreateDateTimeFromMilliseconds Creates a DateTime from milliseconds since 1970, 00:00:00 GMT.
CreateDateTimeFromString Creates a DateTime from a string.
DateTimeEquals Checks to see if two DateTimes are equal and returns a boolean result.
DateTimeNotEquals Checks to see if two DateTimes are not equal and returns a boolean result.
FormatDateTime Used to convert a DateTime to a formatted string.
GetCurrentDateTime Gets current Date and Time. Returns a DateTime value.
GetDayOfMonth Gets the day of the month from a DateTime, and returns a numeric value from 1 to 31. Returns null if the specified DateTime is null.
GetDayOfWeek Gets the day of the week for the DateTime, and returns a numeric value from 1 to 7.
GetDayOfYear Gets the day of year field value. Return null if the specified date time is null.
GetDaysBetween Gets the number of days between two DateTime values, and returns a numeric value.
GetHourOfDay Gets the hour of the day from a DateTime and returns a numeric value from 0 to 23. Returns null if the specified DateTime is null.
GetMilliseconds Gets the number of milliseconds since 1970, 00:00:00 GMT for the DateTime, and returns numeric value. Returns null if the specified DateTime is null.
GetMinuteOfHour Gets the minute of the hour, from 0 to 59.
GetMonthOfYear Gets the month of the year from a DateTime and returns a numeric value from 1 to 12. Returns null if the input is null.
GetSecondOfMinute Gets the second of the minute from a DateTime and returns a numeric value from 0 to 59. Returns null if the input is null.
GetYear Gets the year from a DateTime and returns a numeric value.
SubtractDateTime Subtracts two DateTimes and returns a new DateTime.
Note: Ruleset Actions provides additional details for these and other Actions.

Creating a DateTime Variable

These steps take place in the Ruleset editor's Variables section.
  1. Click Add Variable.
  2. Type the name you wish to give the variable.
  3. Select DateTime from the Type drop-down.
  4. Click OK to complete this task.

Result: The new variable now appears (identified as ) as an option in the Variables pane.

Example

This simple example shows how you might use a DateTime variable with several Actions. We will use the DateTime variable to set an initial value for a specific date - 12192000. We will then take that variable and add one day using another action. Finally we will format and write the output.

Three Actions will accomplish this:
  • CreateDateTimeFromString
  • AddDateTimeWithFields
  • FormatDateTime

But first we must create the DateTime variable from the Ruleset editor.

This variable, named "DT", is now available for use from the Variables pane.

Action: CreateDateTimeFromString

  • Define Inputs (12192000)
  • Define the pattern (mmddyyyy)
  • Use "DT" as output.

Action: AddDateTimeWithFIelds

  • Define inputs, using "DT"
  • For DayOfMonth, define as “1”. For this example, we are simply adding one day to the initial DateTime.
  • Again, use "DT" as output.

Action: FormatDateTime

  • Define inputs, using "DT".
  • Define the pattern. (mmddyyyy)
  • Write the string out to target.

Now that we have our three Action used as Rule in the Ruleset, we can run the transformation and test the output.

Result: Initial source DateTime of 12192000 is written to target (Field 1) as 12202000.

List Variables

The List variable can be used to store groups of Boolean, String, or Numeric data types within a Ruleset.

This can be used to accomplish different use cases:
  • Selectively extract values for use in rules in the Ruleset.
  • Called as a looping construct in a Composite Rule.

In conjunction with this variable type, several List-related Ruleset Actions are available. 

 
Action Description
CreateList This Action returns a new empty list of the defined variable type, and is used with these Actions below.
ListAdd Adds an element to the specified list. Inputs are:
  • list: The list that is being added to.
  • element: The element that is being added to the list.
ListSize Returns the number of elements in a specified list. This has one input:
  • list: The list being measured.
ListGet Returns an element from a list at a specified position. Inputs are:
  • list: The list that being inspected.
  • index: The position of the element to be listed. The position index starts at 1.
CreateRange Returns a read-only list of numbers; starting and stopping at user-defined values. This list can then be used to create a looping construct in conjunction with a Composite Rule. Inputs are:
  • rangeStart: The starting position of the range.
  • rangeEnd: The ending position of the range.
  • rangeStep: The interval at which looping occurs within the range. For example, in a range list of 10, a rangeStep of "2" would result in 5 loops.

Creating a List Variable

These steps take place in the Ruleset editor's Variables section.
  1. Click Add Variable.
  2. Type the name you wish to give the variable.
  3. Select List from the Type drop-down.
  4. Select the Element Type. Choices are Boolean, String, and Number.
  5. Click OK to complete this task.

Result: The new variable now appears as an option in the Variables pane.

Example

This simple example shows how you might use several of the Actions with the List variable type.

The first Rule uses the CreateList Action, which uses the List-type variable that we already created – ListField.

The next Rule - a For Each Composite Rule - shows that it contains five child rules. All but one are Move rules; the second Rule down is another Collection Rule – ListAdd, which in this case will add an element (“Field 2”) to the “ListField” list.

Another Composite Rule (For each ListField….) creates a new record for each element in the List. In this case we only have one element, “Field 2”. The output below shows how these rules could execute.

While this example may be simple, it demonstrates the two use cases noted above.

Duration Variables

The Duration Ruleset variable type can be used to calculate the time between two DateTime variable types, or used to increment/decrement a DateTime value. You can safely manipulate duration values in your data without the need for manual editing or custom rules.

In conjunction with this variable type, several new Actions are available in the Ruleset to support the Duration type.

 
Action Description
CreateDuration This task creates a Duration variable to be used with a DateTime variable.
CalculateDuration This task calculates the time between two DateTime variables.
DurationEquals This task checks to see if two Duration variables are equal and returns a boolean result.
AddDurationtoDateTime This task adds to or increments Duration from the DateTime value.
SubtractDurationFromDateTime This task subtracts or decrements Duration from the DateTime value.
Note: Ruleset Actions provides additional details for these and other Actions.
 

Creating a Duration Variable

These steps take place in the Ruleset editor's Variables section.
  1. Click Add Variable.
  2. Type the name you wish to give the variable.
  3. Select Duration from the Type drop-down.
  4. Click OK to complete this task.

Result: The new variable (shown as ) now appears as an option in the Variables pane.

Example

This Ruleset example shows four Composite Rules using the Duration variable type and several supporting Actions.

Each Composite Rule is working with a common DateTime variable having these values.

Composite Rule #1

 

Composite Rule #2

Composite Rule #3

Composite Rule #4

 

StorageNode Variables

The StorageNode variable type holds the representation of data that may be defined by a Schema.

This variable type can now be used as a Source and/or Target for a Ruleset Method, which can now transform data that is created/retrieved within the Ruleset; data that may have a Schema which differs from the Ruleset’s Source/Target. This allows you to transform more data without having to build multiple Rulesets to do so.

Note: This variable type is currently supported in newer generations of the transformation engine only.

Creating a StorageNode Variable

These steps take place in the Ruleset editor's Variables section.
  1. Click Add Variable.
  2. Type the name you wish to give the variable.
  3. Select StorageNode from the Type drop-down.
  4. Click OK to complete this task.

Result: The new variable now appears (identified as ) as an option in the Variables pane.

Related articles

Comments

0 comments

Please sign in to leave a comment.