HowToUse

How to use the library to run a 3e process

First, create a new Process object. The first parameter is the name of custom 3e Process, and the second is the name of the 3e Object being manipulated. For example:

var p = new Process("WsMatter", "Matter");

Add, Edit or Delete

You then need to specify the operation to perform. To insert a new record, use:

var op = p.AddOperation();

To update or delete a record you need to specify which record. The first way is to pass in the primary key value which will be either a string, an integer, or a guid:

var op = p.EditOperation(12345);

Some archetypes in 3e like Matter, Client, Timekeeper, and BankAcct have an alias property which you can use as an alternative identifier. You should specify the name of the alias column, and the alias value itself will always be a string:

var op = p.EditOperationByAlias("Number", "LS1000.00001");

You can also select a record by its position:

var op = p.EditOperationByPosition(0);

though this option is more useful when a child record needs to be updated.

You can perform more than one operation within the same call to the process by simply adding additional Add, Edit or Delete operations:

p.DeleteOperationByAlias("Number", "MT1000.99999");
p.DeleteOperationByAlias("Number", "MT1000.99998");
p.DeleteOperationByAlias("Number", "MT1000.99997");

A delete operation will delete the specified record, plus any and all related child records as defined by the definition of the 3e Object.

Set attribute values

For add and edit operations you need to specify the new attribute values:

op.AddAttribute("Description", "A new matter");

Attributes are defined by the 3e object rather than the archetype and so may include items that have no physical presence in the database:

op.AddAttribute("IsAutoNumbering", true);

You can, as before, specify values using an alias property:

op.AddAttribute("Client", "Number", "LS1000");

You can pass in a null value for a integer, decimal or datetime:

decimal? budgetAmount = null;
op.AddAttribute("Budget", budgetAmount);

Just like inserting or updating a record in a database, you must ensure that no attributes on the object that are marked as required are left unset. That means for an add operation, you must add at least all the attributes that are marked required (and give them non-null values). You do not need to add attributes that are marked AutoNumber. For an edit operation you can add as many or as few attributes as you like, but no required attribute must be set to a null value.

Children

Many objects, like Matter, have one or more associated child records and you can update values in these children at the same time. To add a child use:

var md = a.AddChild("MattDate");

where the parameter is the name of the child object. The order that you add the children can be important. If you are adding more than one child then it can be worth checking the xsd schema that describes the object. These can be found in the TE_3E_Share\TE_3E_instance\Inetpub\XML\Object\Schema\Write directory and there will be a file for each object in 3e. For example the Matter.xsd file contains the following:

  <xs:complexType name="Matter_EditChildren">
    <xs:complexContent>
      <xs:extension base="transerv:EditChildren">
        <xs:sequence>
          <xs:element name="MattDate" type="obj:Matter_MattDate_EditChild" minOccurs="0" />
          <xs:element name="MattSite" type="obj:Matter_MattSite_EditChild" minOccurs="0" />
          <xs:element name="MattBillingContact" type="obj:Matter_MattBillingContact_EditChild" minOccurs="0" />
          <xs:element name="MattRate" type="obj:Matter_MattRate_EditChild" minOccurs="0" />
          <xs:element name="RateExc" type="obj:Matter_RateExc_EditChild" minOccurs="0" />
          <xs:element name="MattTaxonomy" type="obj:Matter_MattTaxonomy_EditChild" minOccurs="0" />
          <xs:element name="MatterRateExc" type="obj:Matter_MatterRateExc_EditChild" minOccurs="0" />
          <xs:element name="MattTemplateOption" type="obj:Matter_MattTemplateOption_EditChild" minOccurs="0" />
          <xs:element name="BillingGroupMatter1" type="obj:Matter_BillingGroupMatter1_EditChild" minOccurs="0" />
          <xs:element name="MattProfAdjust" type="obj:Matter_MattProfAdjust_EditChild" minOccurs="0" />
          <xs:element name="MaskOverrideValues" type="obj:Matter_MaskOverrideValues_EditChild" minOccurs="0" />
          <xs:element name="MattBudget" type="obj:Matter_MattBudget_EditChild" minOccurs="0" />
          <xs:element name="MattFlatFee" type="obj:Matter_MattFlatFee_EditChild" minOccurs="0" />
          <xs:element name="MattPhaseException" type="obj:Matter_MattPhaseException_EditChild" minOccurs="0" />
          <xs:element name="MattIndustryGroup" type="obj:Matter_MattIndustryGroup_EditChild" minOccurs="0" />
          <xs:element name="MattPracticeTeam" type="obj:Matter_MattPracticeTeam_EditChild" minOccurs="0" />
          <xs:element name="MattCostTypeSummarize" type="obj:Matter_MattCostTypeSummarize_EditChild" minOccurs="0" />
          <xs:element name="CmCase" type="obj:Matter_CmCase_EditChild" minOccurs="0" />
          <xs:element name="MattPayor" type="obj:Matter_MattPayor_EditChild" minOccurs="0" />
          <xs:element name="MattTrust" type="obj:Matter_MattTrust_EditChild" minOccurs="0" />
          <xs:element name="MattTaxArticle" type="obj:Matter_MattTaxArticle_EditChild" minOccurs="0" />
          <xs:element name="MattNote" type="obj:Matter_MattNote_EditChild" minOccurs="0" />

          any custom children that you have created will appear here...
        </xs:sequence>
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>

So you can see that MattDate is the first child and must be added before MattRate.

You must now choose the operation to perform on the child record. This uses exactly the same interface as the parent object, so for example:

var child = matterEditOperation.AddChild("BillingGroupMatter1");
var addChild = child.AddOperation();
addChild.AddAttribute("BillingGroup", billingGroupName);

There is stock code in the Matter object definition that automatically adds a child MattDate and a child MattRate record when a new Matter record is started. When adding a new Matter record, you should therefore get access to these records by position:

var md = a.AddChild("MattDate").EditOperationByPosition(0);
md.AddAttribute("EffStart", today);

var rate = a.AddChild("MattRate").EditOperationByPosition(0);
rate.AddAttribute("Rate", "HEADLINE");
rate.AddAttribute("IsActive", true);

There is no reference that you can refer to in order to determine whether a child is automatically added, but you can observe the behaviour in the front end of 3e.