Business Operation in Console

RunCmd utility supports a range of commands which provides executing of the Business Operations. This topic describes this commands.

BusinessOperationHelp

BusinessOperationHelp command (short name is boph).

It displays the current description. It requires no additional parameters.

Examples of use:

  • example

RunCmd BusinessOperationHelp
 RunCmd boph

BusinessOperationList

BusinessOperationList command (short name is boph).

It writes a list of allowable Business Operations. It requires no additional parameters.

Examples of use:

  • example

RunCmd BusinessOperationList
 RunCmd bopl

BusinessOperationHelpInfo

BusinessOperationHelpInfo command (short name is bopi).

It writes a detailed description of specified Business Operation. It requires one parameter: the ID of any operation from the BusinessOperationList list. I.e. it could be any Business Operation registered in the system and returned by the BusinessOperationList command.

Examples of use:

  • example

RunCmd BusinessOperationInfo Id:"Xafari.Northwind.DC.BusinessOperations.ChangeFreightContext"
 RunCmd bopi Id:"Xafari.Northwind.DC.BusinessOperations.ChangeFreightContext".

BusinessOperationRun

BusinessOperationRun command (short name is bopr).

It executes or rolls back specified Business Operation. It requires a number of parameters:

1. The ID of  Business Operation.

2. Method to be called. There is optional `Method' parameter, it may be `Execute' or `Rollback'.

3. Parameters. As is known, the Business Operation may have a set of input parameters. You can initialize it in this section. The ways to set parameters are described below.

Examples of use:

  • example

RunCmd BusinessOperationRun Id:"SomeReversibleBusinessOperation" Method:Rollback
 RunCmd bopr Id:"SomeReversibleBusinessOperation"

There are some ways to set parameters of Business Operation when running in console.

1. You can specify parameters explicitly when invoke BusinessOperationRun command, just list them in the form of <name>:<value> pairs, separated by a space. In general, the rules of writing values to a string comply  the rules of the Windows command-line. The value can be transferred to any text without spaces and ' " ' characters. If you need to set value with space or ' " ' character, you must enclose the entire value in double quotes. All the ' " ' characters within a value must be doubled.

Examples of use:

  • example

RunCmd BusinessOperationRun id:"Xafari.Northwind.DC.BusinessOperations.ChangeFreightContext" Orders:"[{""Oid"":""B95C5919-1562-401A-A26F-00094911E33A""}]" Percent:10

To set the parameters of complex types, including persistent, use JSON notation. It may be JSON-string in command line or file in JSON format.

2. To initialize Business Operation from command line use JsonStr parameter within BusinessOperationRun command. The value of JsonStr parameter is a string in JSON format. When you write this string, you have to follow the Windows command-line rules.

Example:

  • example

RunCmd BusinessOperationRun id:"Xafari.Northwind.DC.BusinessOperations.ChangeFreightContext" jsonstr:"{""Orders"":[{""Oid"":""B95C5919-1562-401A-A26F-00094911E33A""}], ""Percent"":10}"

3. To initialize Business Operation from JSON -file use JsonFile parameter within BusinessOperationRun command. The value of JsonFile parameter is a file name, file contains JSON-text.

Example:

  • example

RunCmd BusinessOperationRun id:"Xafari.Northwind.DC.BusinessOperations.ChangeFreightContext" jsonfile:json.txt
 Contents of the json.txt file:
 {
  "Orders":[{"Oid":"B95C5919-1562-401A-A26F-00094911E33A"}],
  "Percent":10
 }

When you write JSON -file, you have to follow the JSON format rules only.

How to set BO parameters with JSON: basic principles.

The description is based on the example given below.

Specify the values of simple types (byte, sbyte, short, ushort, int, uint, long, ulong, float, double, decimal, enum) directly, without the quotes. It is also possible to use quotes (string representation). In this case TypeConverter instance of the corresponding target type converts the string to value.

Specify the values of String, Uri and Guid types as a string (enclosed in quotes). In the same manner you can set Enum value. See StringProp, GuidProp, UriProp, EnumProp2 properties in example below.

To specify the values of DateTime or DateTimeOffset types it is recommended to use string format, regardless of culture ("o", "r", "R", "s", "u", U" formats). RunCmd also supports the approach described in the System.Web.Script.Serialization.JavaScriptSerializer class description (see links below). See DateTimeProp1, DateTimeProp2, DateTimeOffsetProp properties in example below.

To set Collection properties use JSON arrays notation: the list of values enclosed in '[' and ']' characters, values separated by commas (`,').  See IntArrayProp, GenericListOfStrings, ArrayListProp properties in example below.

To set Object properties (reference properties) use JSON objects notation: the list of fields enclosed in '{' and '}' characters. See XpoPersistentProp, XpoUntypedPersistentProp, SimpleClassProp properties in example below.

If there is not registered a separate converter for type, then the deserializer uses the activator when creating an instance of the object. It is default behavior. Therefore, the class must have a default constructor.

When initialize property with certain object it is possible to specify the type of the object. For this purpose "__type" key is intended. See XpoUntypedPersistentProp property in example below. Instance will be created either activator or registered converter.

Persistent Parameters

There are several ways to specify persistent object (see

initialization of XpoPersistentProp, XpoPersistentListProp properties in sample below):

1. Specify only key-property of JSON object and set it's string value (see "Oid" property in sample).

Key field name must match the real name of the key field of the persistent object. When such an object is deserialized framework searches an object by a key in the database (ObjectSpace.GetObjectByKey method).

2. Specify some of properties and it's values for JSON object. When such an object is deserialized framework creates a criteria based on the specified properties. For example: "[property_1]=value_1 AND [property_2]=value_2 AND : ". Search in database will be started and the first suitable object will be retrieved (ObjectSpace.FindObject method).

3. Specify JSON object using special "__criteria" key. In this case, you can specify an arbitrary criterion. When such an object is deserialized framework will pass criterion string to CriteriaOperator.Parse() method. Then this criterion is combined with the other (if any) by AND operation. Search in database will be started and the first suitable object will be retrieved (ObjectSpace.FindObject method).

To deserialise JSON format, framework uses the System.Web.Script.Serialization.JavaScriptSerializer class. See http://msdn.microsoft.com/en-us/library/system.web.script.serialization.javascriptserializer(v=vs.110).aspx topic.

For more information, see:

http://json.org/json-en.html

https://en.wikipedia.org/wiki/JSON

http://msdn.microsoft.com/en-us/library/bb299886.aspx#intro_to_json_topic5

Example

Business Operation class:

  • example

public class BusinessOperation1 : BusinessOperationBase
 {
     public byte ByteProp { get; set; }
     public sbyte SbyteProp { get; set; }
     public short ShortProp { get; set; }
     public ushort UshortProp { get; set; }
     public int IntProp { get; set; }
     public uint UintProp { get; set; }
     public long LongProp { get; set; }
     public ulong UlongProp { get; set; }
     public char CharProp { get; set; }
     public float FloatProp { get; set; }
     public double DoubleProp { get; set; }
     public decimal DecimalProp { get; set; }
     public String StringProp { get; set; }
     public Guid GuidProp { get; set; }
     public Uri UriProp { get; set; }
     public TestEnum EnumProp1 { get; set; }
     public TestEnum EnumProp2 { get; set; }
     public DateTime DateTimeProp1 { get; set; }
     public DateTime DateTimeProp2 { get; set; }
     public DateTimeOffset DateTimeOffsetProp { get; set; }
     public int[] IntArrayProp { get; set; }
     public IList<string> GenericListOfStrings { get; set; }
     public ArrayList ArrayListProp { get; set; }
     public XpObject1 XpoPersistentProp { get; set; }
     public IList<XpObject1> XpoPersistentListProp { get; set; }
     public object XpoUntypedPersistentProp { get; set; }
     public SimpleClass SimpleClassProp { get; set; }
 }

 public class XpObject1 : BaseObject
 {
     public XpObject1(Session session) : base(session) {}
     public int Code {
         get { return GetPropertyValue<int>("Code"); }
         set { SetPropertyValue("Code", value); }
     }
     public string Name {
         get { return GetPropertyValue<string>("Name"); }
         set { SetPropertyValue("Name", value); }
     }
 }

 public class SimpleClass
 {
     public string Name { get; set; }
     public int Count { get; set; }
 }

 public enum TestEnum { One = 1, Two =2, Three = 3 };

JSON file to initialize Business Operation:

  • example

{
  "ByteProp" : 251,
  "SbyteProp" : -125,
  "ShortProp" : -32768,
  "UshortProp" : 65535,
  "IntProp" : -2147483648,
  "UintProp" : 4294967295,
  "LongProp" : -9223372036854775808,
  "UlongProp" : 18446744073709551615,
  "CharProp" : "c",
  "FloatProp" : -3.402823e38,
  "DoubleProp" : 1.79769313486231e308,
  "DecimalProp" : -79228162514264337593543950335,
  "StringProp" : "test",
  "GuidProp" : "c1bb3433-c01a-4e63-b1a2-950c37b3ebff",
  "UriProp" : "http://www.xafari.net/",
  "EnumProp1" : 1,
  "EnumProp2" : "Two",
  "DateTimeProp1" : "\/Date(1411108851925)\/",
  "DateTimeProp2" : "2000-01-02T17:18:19",
  "DateTimeOffsetProp" : "2014-09-19T10:06:34+03:00",
  "IntArrayProp" :[23,42,120],
  "GenericListOfStrings" :["glsitem0", "glsitem1"],
  "ArrayListProp" :["alitem0", 123],
  "XpoPersistentProp" :{"Oid":"B95C5919-1562-401A-A26F-00094911E33A"},
  "XpoUntypedPersistentProp":{"__type":"Tests.XpObject1", "Oid":"B95C5919-1562-401A-A26F-00094911E33A"},
  "XpoPersistentListProp" :
      [
         {"Oid\" :"B95C5919-1562-401A-A26F-00094911E33A"},
         {"__criteria":"[Code] = 5 OR [Code] = 6\"},
         {"Code" :3},
         {"Name" :"NX"},
         {"Oid" :"B95C5919-1562-401A-A26F-00094911E33A", "Code":2}
      ],
  "SimpleClassProp" :{"Name":"name_value", "Count":456 }
 }