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, a guid, or a date:

var op = p.EditOperation(12345);

Some archetypes in 3e like Matter, Client, Timekeeper, and BankAcct have an alternative unique identifier which provide a more user-friendly way to identify a particular record. For example, you can start an edit operation on a Matter record by specifying the value of the matter number:

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

You can specify any attribute on the underlying archetype as the alias column to search, but the search must result in finding one and only one record so the value must be unique within the entire table of records.

When you want to edit or delete a record in a child collection, there are two more options that become available. Firstly, you can select a record by its position:

var op = p.EditOperationByPosition(0);

The position parameter indicates the zero-based index within the child collection. You would typically use this option when creating a new matter or timekeeper.

Secondly, you can select a record by searching the child collection for a particular value in a specified field:

var op = p.EditOperationByKeyField("EffStart", dateFinancialYearBegan);

The first record in the child collection which matches the criteria will be returned. This can be useful for selecting a particular effective dated record, as the date will be unique within the child collection though not unique throughout the entire table.

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. Attributes and children cannot be specified on a Delete operation.

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" />
        </xs:sequence>
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>

So you can see that MattDate is the first child and must be added before MattRate. Note that any custom objects that have been added to Matter as a child will also be listed in the above schema.

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.

Run the Process

There are two ways to run the action(s) that have been constructed using the process object. The quick and simple way is

RunProcess.ExecuteProcess(Process p, WindowsIdentity wi = null, string endpointName = null)

p is the process object constructed above,
wi is an optional parameter specifying the windows account which will be used to run the process. The account must therefore be registered in 3e and be granted the correct permissions. If this parameter is not specified then 3e will try to run the specified process in the context of the account being used to run the application.
endpointName is an optional parameter specifying which endpoint in the .config file will be used. This can be used to select between different 3e environments. If more than one endpoint has been defined then this parameter must be specified.

The second way is to pass in a RunProcessParameters object. The object has the following properties:

Request: an XmlDocument that contains the actual request to be submitted to 3e. This property will be automatically populated when a Process is passed during construction.
GetKey: a boolean that indicates whether to try to return the primary key of a newly added record. This can be used to determine the index of a new matter record, and also returns newly created guids too.
AccountToImpersonate: a WindowsIdentity object that specifies which user account to run the 3e process as.
EndpointName: the name of the endpoint to use for connecting to the required 3e instance, as defined in the application's .config file
ThrowExceptionIfProcessDoesNotComplete: a boolean indicating that the library should check if the request completed and throw an exception when it doesn't. This could happen if you try to call an out of the box 3e process that contains a page step. Normally you'd set this, but if your process is designed as a workflow which should be left on a user or group's dashboard then clear this flag.

Provide feedback

Saved searches