Community Docs Wiki

Community Developer Documentation

Todd Lantry (he/him) — Tue, 14 Oct 2025 19:53:56 GMT

Current Revision posted to Community Docs Wiki by Todd Lantry (he/him) on 10/14/2025 7:53:56 PM

Use this space to write and share documentation on Tessitura functionality that doesn't already exist, but you would have found useful for one of your own projects.

In Slack, you can summon a link to this page with the command !wiki.

...

The Secret Life of HTML Templates

Nick Reilingh — Thu, 11 Apr 2024 18:45:32 GMT

Current Revision posted to Community Docs Wiki by Nick Reilingh on 4/11/2024 6:45:32 PM

or: How I Learned to Stop Worrying and Just Write HTML Templates

or: HTML Templates: The Missing Manual

or: The HTML Templates documentation they don't want you to know about!

This article aims to explain the differences between the Razor template syntax used in Tessitura HTML Templates and the syntax that you might see used in training courses for Razor Pages in ASP.NET Core/MVC web applications. At present, the Tessitura documentation only scratches the surface of what is available syntactically, and doesn't really attempt to explain how HTML Templates are implemented.

Tessitura	v15.1	v16
Razor	ASP.NET MVC 3?	?
C#	5.0	6.0?
RazorEngine	3.10	?

The Big Secret

HTML Templates are rendered using an Apache-licensed, open-source project called RazorEngine, which is available on GitHub. To summarize the RazorEngine documentation, RazorEngine is a framework which consumes the Razor parser -- as is ASP.NET MVC. There is a difference between Razor's syntax and special features provided by these frameworks. RazorEngine only shares its syntax with other implementations like ASP.NET MVC. This is why convenience methods like @Html.Raw() (often seen in web results about Razor Pages) do not work in HTML templates -- the @Html helper is a class specifically implemented by the ASP.NET MVC framework. (RazorEngine instead has @Raw() built-in to provide the same functionality.) Reading the RazorEngine documentation can be informative. Tessitura appears to implement version 3.10 of RazorEngine.

The fundamentals of how Razor operates still apply. The Razor syntax parser converts a .cshtml template into a C# Execute() method on a generated class, which, when invoked, has access to the provided model and returns a string.

Assorted Syntactic Tips and Tricks

The version of C# available in Tessitura HTML Templates in Tessitura V15.1 is C# 5.0. In Tessitura V16, Razor templates will support C# 9.0, giving them support for interpolated strings (C# 6.0), local functions (C# 7.0), and other features.

The version of Razor available in Tessitura HTML Templates in V15.1 is "Razor 3", which is versioned as such because it shipped with ASP.NET MVC 3. This means technically, the syntax documentation linked in the Tessitura docs is WAY too new for what is actually in use. This explains why "templating methods" described in these docs are not functional in Tessitura HTML Templates.

Razor supports the use of a @functions directive, which gives you a space to define additional members (methods and properties) to be added to the generated class. Curiously, the HTML Templates editor does not syntax-color code inside of a @functions directive.

@functions {
    private string SOME_URL_CONSTANT = "https://example.com";
    private string LinkTag(string link) {
        return "<a href=\"" + SOME_URL_CONSTANT + "\">" + link + "</a>";
    }
}
@Raw(LinkTag("some text"))
@* Outputs:
<a href="https://example.com">some text</a>
*@

Methods are private because the template's execution is just another method in the same class.

The version of Razor used in RazorEngine 3.10 (Razor 3, shipped in ASP.NET MVC 3) also supports the @helper directive, which allows you to define a kind of function that contains markup, just like the rest of the template. This allows for easy reuse of template code. Helpers were removed in Razor 4, reappear in ASP.NET MVC 5, were removed again in ASP.NET Core, and finally code blocks were enhanced to allow for inline markup in functions, without the need for the @helper directive. Helpers can be used as "templating methods" which are otherwise unavailable as described above.

@helper BoldMe(string content) {
    <b>@content</b>
}
@BoldMe("look at me, I'm bold!")
@* Outputs:
<b>look at me, I&#39;m bold!</b>
*@

The output of the helper correctly writes literal or encoded HTML like the rest of the template does.

A regular function can be made to behave like a templating method by defining it with a void type and then calling the imperative WriteLiteral() and Write() functions, which is basically what a Razor template compiles to in the first place. Then this function can be called inside a code block (@{}) to inject its output at that location.

@functions {
    private void DIYRenderFunction(string content) {
        WriteLiteral("<p>");
        Write(content);
        WriteLiteral("</p>");
    }
}
@{ DIYRenderFunction("here are my paragraph tags & encoded content"); }
@* Outputs:
<p>here are my paragraph tags &amp; encoded content</p>
*@

Helpers can be passed into one another as arguments if your types are correct. The defined helper token refers to a method which returns a RazorEngine.Templating.TemplateWriter type, which is what writes template content as Literal or HTML-encoded inline. This type has a .ToString() method which can be used to cast to a string type at the point of use, but this is often non-optimal because if the helper template outputs HTML (which it often will), you will need to @Raw() the result when using it in another helper template. Luckily, C# supports the dynamic keyword in a type signature, which means you can pass in either a TemplateWriter or a raw string and RazorEngine will do the right thing at runtime:

@helper ItalicizeMe(dynamic content) {
    <i>@content</i>
}
@helper BoldMe(dynamic content) {
    <b>@content</b>
}
@ItalicizeMe(BoldMe("I'm bold, AND italic!"))
@ItalicizeMe("I'm only italic!")
@* Outputs:
    <i>    <b>I&#39;m bold, AND italic!</b>
</i>
    <i>I&#39;m only italic!</i>
*@

You can also compose helpers by nesting them inside each other's templates, since helpers and @functions directives share the same scope (the generated class). In contrast, variables declared in a code block are local to the render method, so while they can be referenced in the template itself, they cannot be referenced in other class methods like helpers and functions.

A special syntax exists in Razor 3 for raw text. This is necessary when using helpers without surrounding tags. Information here: ASP.NET MVC 3: Razor’s @: and <text> syntax

Now, with all of these tools in our toolbox, only one question remains... Can we avoid writing inline styles?

Tags: c#, HTML Templates, razor

Browser-based custom screen auth token API authentication

Nick Reilingh — Thu, 07 Mar 2024 17:11:00 GMT

Current Revision posted to Community Docs Wiki by Nick Reilingh on 3/7/2024 5:11:00 PM

Per the Tessitura Custom Screens (v15.0+) documentation, browser-based custom screens can be requested with an <<auth>> token passed as a URL parameter. This token represents the Tessitura Client's currently logged-in user's application session, and can be used to authenticate API requests with the user's security context.

This style of session token authentication is far preferable to the alternative, where the web application providing the browser-based custom screen must authenticate to the API as itself, be granted access to a maximum resource scope, and implement resource security on behalf of the API services based on the current user's usergroup. To do this securely, the web application must also request the user to log into itself, inside of a custom tab inside a Tessitura client app session that the user has already authenticated to. This complicates security implementation and the double-login requirement makes for bad UX.

To make use of this method of authentication, the custom web application can be largely if not entirely stateless. The only tradeoff is that API resource permissions must be granted to the Tessitura User Groups that the users operate under. In the case of custom tabs/screens, it would be advisable to bundle appropriate API permissions with access to the custom screen security object itself.

The authentication flow looks something like this:

TR_CUSTOM_TAB is configured with an entry for https://your.app/?token=<<auth>>, and usergroups are granted permission to this custom tab and to any API Resources that will need to be accessed (logging in as an Admin group circumvents this requirement and can be useful for testing).
User opens the custom tab. Custom web app receives a GET request from the embedded browser containing the auth token in the URL.
Web app must parse URL parameters obtaining the token value, decoding any URL %-encoding which is likely to occur in the auth token parameter. Most libraries and frameworks will do this automatically.
Web app can now make a request to the Tessitura API. Instead of using traditional basic auth (Username:Usergroup:Location:Password), the request can simply provide a token authorization header as follows: Authorization: Token <token>.

Depending on the specific needs of the web app, it is likely advisable for the token to be returned back to the frontend as a session cookie, since the URL parameter provided by Tessitura is only guaranteed when the custom screen is loaded for the first time (or reloaded). Any navigations the user does from within the custom screen (e.g. by clicking an <a> tag) will navigate to whatever href has been provided by the web app. An app developer may opt to provide the auth token in all such hrefs instead of using the session cookie approach, but this is up to personal taste.

Tags: Authentication, authorization, custom screens, REST API

New to Using Tessitura in a Software Developer Role? Start here!

Marcus Johnson — Wed, 22 Mar 2023 19:17:43 GMT

Current Revision posted to Community Docs Wiki by Marcus Johnson on 3/22/2023 7:17:43 PM

Are you a developer looking to build Tessitura-powered applications but don't know where to start? Look no further! Our documentation space is here to help you get started with our easy-to-follow getting started guide. With links to the API Resources page, REST API Help Documentation, SOAP API Guide v15 and the SOAP to REST Transition Guide, we have all the resources you need to start building your Tessitura-powered applications.

Developer Basics

Registered Developers have access to Tessitura documentation including API help pages. application documentation and best practice advice. If the company has access, they may register an account under it; if not, request access.
Community forums and Topical community group – Get answers today from other Tessitura developers in the forums and engage with other developers on Developer User Group virtual meetups.
Slack Channel – Have a question? Chat with other developers about the Tessitura API, web development, SQL, HTML Templates, Community Source projects, and more.
Shared Code Repository – Stumped for a solution? Interested to see how others have solved similar problems? Take a peek at projects other developers have chosen to share in our community's shared code repository.

Additional Resources

Videos detailing the basics of the Tessitura API and what you can do with them.
SOAP API Guide v15 – Full listing of methods available via the Tessitura SOAP API.

Show Information from a Custom Data Service

John A. Moskal II — Wed, 08 Mar 2023 16:30:53 GMT

Current Revision posted to Community Docs Wiki by John A. Moskal II on 3/8/2023 4:30:53 PM

This is an example of fetching and displaying in an HTML Template e-mail, arbitrary data from a custom Data Service Table/View stored in TR_DATASERVICE_TABLES. Updates/edits welcome.

In this example, we reference a local database view LVXS_CP_ORDER_PRIMARY_ORG with the name CPOrdersPrimaryOrg and unique key column of order_no. Sample reason this might be needed is in a consortium environment where orders might feature products from multiple organizations and there is a need to determine a primary/joint style/content template for the e-mail.

@* Sample get single custom dataservice element based on ID *@

@* Use Newtonsoft.Json for parsing *@
@using Newtonsoft.Json;
@using Tessitura.Services.Common.Client.Utils;

@* Define object CPOrderOrg for properly named and typed results *@
@functions
{       
    public class CPOrderOrg
    {
        [JsonPropertyAttribute("organization")]
        public int OrgId;
        [JsonPropertyAttribute("org_desc")]
        public string OrgDesc;
    }
}

@* Define URL for and get data from custom dataservice entry CPOrdersPrimaryOrg based on the Order ID; single object results *@
@{
    @* Order ID is provided in the Order Confirmations template type *@
    var customURL = "Custom/CPOrdersPrimaryOrg/" + Model.OrderProductView.Id;
    var orderPrimaryOrg = Model.RestClient
        .AtUrl(customURL)
        .WithContentType(ContentType.Json)
        .Get<CPOrderOrg>()
        .ResponseObject;
}

@* Output results *@
<p>
    @orderPrimaryOrg.OrgId
    @orderPrimaryOrg.OrgDesc
</p>

Tags: HTML Templates, razor, REST API

Show Information from a Custom Data Service

John A. Moskal II — Wed, 08 Mar 2023 16:29:45 GMT

Revision 1 posted to Community Docs Wiki by John A. Moskal II on 3/8/2023 4:29:45 PM

This is an example of fetching and displaying in an HTML Template e-mail, arbitrary data from a custom Data Service Table/View stored in TR_DATASERVICE_TABLES. Updates/edits welcome.

@* Sample get single custom dataservice element based on ID *@

@* Use Newtonsoft.Json for parsing *@
@using Newtonsoft.Json;
@using Tessitura.Services.Common.Client.Utils;

@* Define object CPOrderOrg for properly named and typed results *@
@functions
{       
    public class CPOrderOrg
    {
        [JsonPropertyAttribute("organization")]
        public int OrgId;
        [JsonPropertyAttribute("org_desc")]
        public string OrgDesc;
    }
}

@* Define URL for and get data from custom dataservice entry CPOrdersPrimaryOrg based on the Order ID; single object results *@
@{
    @* Order ID is provided in the Order Confirmations template type *@
    var customURL = "Custom/CPOrdersPrimaryOrg/" + Model.OrderProductView.Id;
    var orderPrimaryOrg = Model.RestClient
        .AtUrl(customURL)
        .WithContentType(ContentType.Json)
        .Get<CPOrderOrg>()
        .ResponseObject;
}

@* Output results *@
<p>
    @orderPrimaryOrg.OrgId
    @orderPrimaryOrg.OrgDesc
</p>

Tags: HTML Templates, razor, REST API

Measure and improve SQL query performance

James Murty — Thu, 02 Feb 2023 04:06:50 GMT

Current Revision posted to Community Docs Wiki by James Murty on 2/2/2023 4:06:50 AM

Some tips for writing custom database queries or stored procedures that perform well, or improving the performance of existing SQL.

This page was inspired and informed by a thread in the Tessitura Network Slack. Thanks to all the contributors to that thread.

It can be difficult to evaluate the how quick (or slow) queries are when you run them in SSMS because:

there can be a significant difference between the time to run a query (as reported as SQL Server Execution time) versus the "clock" time to return the results (as shown at the bottom right of the window)
query caching can skew results of re-run queries
general database load can affect timings, if you're writing queries on a live or actively used database (don't do this, if you can help it)

Use these directives to improve the quality and consistency of query metrics, though they may not work on RAMP deployments:

DBCC DROPCLEANBUFFERS
SET STATISTICS IO ON

Change the final statement to `SELECT 1;` to measure just the query time without returning data. If this shows a significant difference in performance you are likely experiencing key lookups, try gradually adding back the real SELECT statements to find the one(s) that are slow. In all cases avoid returning * from tables, only return what you really need.

Tags: performance, database, SQL

Measure and improve SQL query performance

James Murty — Thu, 02 Feb 2023 04:05:13 GMT

Revision 1 posted to Community Docs Wiki by James Murty on 2/2/2023 4:05:13 AM

Some tips for writing custom database queries or stored procedures that perform well, or improving the performance of existing SQL.

This page was inspired and informed by a thread in the Tessitura Network Slack. Thanks to all the contributors to that thread.

It can be difficult to evaluate the how quick (or slow) queries are when you run them in SSMS because:

there can be a significant difference between the time to run a query (as reported as SQL Server Execution time) versus the "clock" time to return the results (as shown at the bottom right of the window)
query caching can skew results of re-run queries
general database load can affect timings, if you're writing queries on a live or actively used database (don't do this, if you can help it)

Use these directives to improve the quality and consistency of query metrics, though they may not work on RAMP deployments:

DBCC DROPCLEANBUFFERS
SET STATISTICS IO ON

Tags: performance, database, SQL

Show information from a custom stored procedure

James Murty — Mon, 05 Dec 2022 05:31:16 GMT

Current Revision posted to Community Docs Wiki by James Murty on 12/5/2022 5:31:16 AM

This is a rough guide to fetching and displaying in an HTML Template email arbitrary data from a custom stored procedure via the Custom/Execute REST API endpoint.

NOTE: This may not be the best way to do things—edits, additions, and improvements to this document are very welcome.

In this example, we use a CUSTOMER_ORDERS stored procedure to include a summary of a constituent's recent orders in a Constituent Info template.

@using Tessitura.Services.Common.Client.Utils;

@using Tessitura.Service.Client.CRM;

@using Tessitura.Service.Client.Custom;

@* Use Newtonsoft library to parse fields from JSON data *@

@using Newtonsoft.Json;

// Define an OrderInfo object to parse JSON data from fields returned by the

// custom query to attributes of the correct type.

@functions {

public class OrderInfo

{

[JsonPropertyAttribute("order_no")]

public int OrderNo;

[JsonPropertyAttribute("order_total")]

public double OrderTotal;

[JsonPropertyAttribute("last_update_dt")]

public DateTime LastUpdate;

}

// Find orders that have been updated in the last 30 days

DateTime now = DateTime.Now;

DateTime ordersFromDate = now.AddDays(-30);

// Define request parameters for CUSTOMER_ORDERS custom stored procedure

LocalProcedureRequest localProcedureRequest = new LocalProcedureRequest

{

ProcedureName = "CUSTOMER_ORDERS",

ParameterValues = new ParameterValues

{

// Constituent ID is made available in Constituent Info templates

new ParameterValue

{

Name = "constituent_id",

Value = Model.ConstituentSnapshot.Id.ToString()

new ParameterValue

{

Name = "start_dt",

Value = ordersFromDate.ToString("yyyy-MM-dd")

}

};

// Fetch data from stored procedure CUSTOMER_ORDERS via /Custom/Execute API

// endpoint and parse JSON response data into a list of `OrderInfo` objects

var orders = Model.RestClient

.AtUrl("Custom/Execute")

// Request JSON data in response

.WithContentType(ContentType.Json)

// POST request, with defined types to (de)serialize req/resp data

.Post<LocalProcedureRequest, List<OrderInfo>>

(localProcedureRequest)

.ResponseObject;

// Uncomment to see JSON response data in the HTML Template editor

<pre>

@Raw(Newtonsoft.Json.JsonConvert.SerializeObject(

@orders,

Newtonsoft.Json.Formatting.Indented

));

</pre>

}

@if (orders.Count > 0)

{

<h1>Customer Orders</h1>

<ul>

@foreach (var order in orders)

{

<li>

@order.OrderNo -

@order.OrderTotal.ToString("C") -

@order.LastUpdate.ToString("dd MMMM yyyy HH:mm tt")

</li>

}

</ul>

<p>

TOTAL: @orders.Sum(o => o.OrderTotal).ToString("C")

</p>

}

Tags: razor, REST API

Show information from a custom stored procedure

James Murty — Mon, 05 Dec 2022 05:28:00 GMT

Revision 3 posted to Community Docs Wiki by James Murty on 12/5/2022 5:28:00 AM

This is a rough guide to fetching and displaying arbitrary data from a custom stored procedure via the Custom/Execute REST API endpoint.

NOTE: This may not be the best way to do things—edits, additions, and improvements to this document are very welcome.

In this example, we use a CUSTOMER_ORDERS stored procedure to include a summary of a constituent's recent orders in a Constituent Info template.

@using Tessitura.Services.Common.Client.Utils;

@using Tessitura.Service.Client.CRM;

@using Tessitura.Service.Client.Custom;

@* Use Newtonsoft library to parse fields from JSON data *@

@using Newtonsoft.Json;

// Define an OrderInfo object to parse JSON data from fields returned by the

// custom query to attributes of the correct type.

@functions {

public class OrderInfo

{

[JsonPropertyAttribute("order_no")]

public int OrderNo;

[JsonPropertyAttribute("order_total")]

public double OrderTotal;

[JsonPropertyAttribute("last_update_dt")]

public DateTime LastUpdate;

}

// Find orders that have been updated in the last 30 days

DateTime now = DateTime.Now;

DateTime ordersFromDate = now.AddDays(-30);

// Define request parameters for CUSTOMER_ORDERS custom stored procedure

LocalProcedureRequest localProcedureRequest = new LocalProcedureRequest

{

ProcedureName = "CUSTOMER_ORDERS",

ParameterValues = new ParameterValues

{

// Constituent ID is made available in Constituent Info templates

new ParameterValue

{

Name = "constituent_id",

Value = Model.ConstituentSnapshot.Id.ToString()

new ParameterValue

{

Name = "start_dt",

Value = ordersFromDate.ToString("yyyy-MM-dd")

}

};

// Fetch data from stored procedure CUSTOMER_ORDERS via /Custom/Execute API

// endpoint and parse JSON response data into a list of `OrderInfo` objects

var orders = Model.RestClient

.AtUrl("Custom/Execute")

// Request JSON data in response

.WithContentType(ContentType.Json)

// POST request, with defined types to (de)serialize req/resp data

.Post<LocalProcedureRequest, List<OrderInfo>>

(localProcedureRequest)

.ResponseObject;

// Uncomment to see JSON response data in the HTML Template editor

<pre>

@Raw(Newtonsoft.Json.JsonConvert.SerializeObject(

@orders,

Newtonsoft.Json.Formatting.Indented

));

</pre>

}

@if (orders.Count > 0)

{

<h1>Customer Orders</h1>

<ul>

@foreach (var order in orders)

{

<li>

@order.OrderNo -

@order.OrderTotal.ToString("C") -

@order.LastUpdate.ToString("dd MMMM yyyy HH:mm tt")

</li>

}

</ul>

<p>

TOTAL: @orders.Sum(o => o.OrderTotal).ToString("C")

</p>

}

Tags: razor, REST API

Show information from a custom stored procedure

James Murty — Mon, 05 Dec 2022 05:25:56 GMT

Revision 2 posted to Community Docs Wiki by James Murty on 12/5/2022 5:25:56 AM

This is a rough guide to fetching and displaying arbitrary data from a custom stored procedure via the Custom/Execute REST API endpoint.

NOTE: This may not be the best way to do things—edits, additions, and improvements to this document are very welcome.

In this example, we use a CUSTOMER_ORDERS stored procedure to include a summary of a constituent's recent orders in a Constituent Info template.

@using Tessitura.Services.Common.Client.Utils;

@using Tessitura.Service.Client.CRM;

@using Tessitura.Service.Client.Custom;

@* Use Newtonsoft library to parse fields from JSON data *@

@using Newtonsoft.Json;

// Define an OrderInfo object to parse JSON data from fields returned by the

// custom query to attributes of the correct type.

@functions {

public class OrderInfo

{

[JsonPropertyAttribute("order_no")]

public int OrderNo;

[JsonPropertyAttribute("order_total")]

public double OrderTotal;

[JsonPropertyAttribute("last_update_dt")]

public DateTime LastUpdate;

}

// Find orders that have been updated in the last 30 days

DateTime now = DateTime.Now;

DateTime ordersFromDate = now.AddDays(-30);

// Define request parameters for CUSTOMER_ORDERS custom stored procedure

LocalProcedureRequest localProcedureRequest = new LocalProcedureRequest

{

ProcedureName = "CUSTOMER_ORDERS",

ParameterValues = new ParameterValues

{

// Constituent ID is made available in Constituent Info templates

new ParameterValue

{

Name = "constituent_id",

Value = Model.ConstituentSnapshot.Id.ToString()

new ParameterValue

{

Name = "start_dt",

Value = ordersFromDate.ToString("yyyy-MM-dd")

}

};

// Fetch data from stored procedure CUSTOMER_ORDERS via /Custom/Execute API

// endpoint and parse JSON response data into a list of `OrderInfo` objects

var orders = Model.RestClient

.AtUrl("Custom/Execute")

// Request JSON data in response

.WithContentType(ContentType.Json)

// POST request, with defined types to (de)serialize req/resp data

.Post<LocalProcedureRequest, List<OrderInfo>>

(localProcedureRequest)

.ResponseObject;

// Uncomment to see JSON response data in the HTML Template editor

<pre>

@Raw(Newtonsoft.Json.JsonConvert.SerializeObject(

@orders,

Newtonsoft.Json.Formatting.Indented

));

</pre>

}

@if (orders.Count > 0)

{

<h1>Customer Orders</h1>

<ul>

@foreach (var order in orders)

{

<li>

@order.OrderNo -

@order.OrderTotal.ToString("C") -

@order.LastUpdate.ToString("dd MMMM yyyy HH:mm tt")

</li>

}

</ul>

<p>

TOTAL: @orders.Sum(o => o.OrderTotal).ToString("C")

</p>

}

Tags: razor, REST API

Show information from a custom stored procedure

James Murty — Mon, 05 Dec 2022 05:21:38 GMT

Revision 1 posted to Community Docs Wiki by James Murty on 12/5/2022 5:21:38 AM

This is a rough guide to fetching and displaying arbitrary data from a custom stored procedure via the Custom/Execute REST API endpoint.

NOTE: This may not be the best way to do things—edits, additions, and improvements to this document are very welcome.

In this example, we use a CUSTOMER_ORDERS stored procedure to include a summary of a constituent's recent orders in a Constituent Info template.

@using Tessitura.Services.Common.Client.Utils;
@using Tessitura.Service.Client.CRM;
@using Tessitura.Service.Client.Custom;

@* Use Newtonsoft library to parse fields from JSON data *@
@using Newtonsoft.Json;

@{
	// Define an OrderInfo object to parse JSON data from fields returned by the
	// custom query to attributes of the correct type.
	@functions {
		public class OrderInfo
		{
			[JsonPropertyAttribute("order_no")]
			public int OrderNo;
			[JsonPropertyAttribute("order_total")]
			public double OrderTotal;
			[JsonPropertyAttribute("last_update_dt")]
			public DateTime LastUpdate;
		}
	}

	// Find orders that have been updated in the last 30 days
	DateTime now = DateTime.Now;
	DateTime ordersFromDate = now.AddDays(-30);

	// Define request parameters for CUSTOMER_ORDERS custom stored procedure
	LocalProcedureRequest localProcedureRequest = new LocalProcedureRequest
		{
			ProcedureName = "CUSTOMER_ORDERS",
			ParameterValues = new ParameterValues
			{
				// Constituent ID is made available in Constituent Info templates
				new ParameterValue
				{
					Name = "constituent_id",
					Value = Model.ConstituentSnapshot.Id.ToString()
				},
				new ParameterValue
				{
					Name = "start_dt",
					Value = ordersFromDate.ToString("yyyy-MM-dd")
				}
			}
		};

	// Fetch data from stored procedure CUSTOMER_ORDERS via /Custom/Execute API
	// endpoint and parse JSON response data into a list of `OrderInfo` objects
	var orders = Model.RestClient
		.AtUrl("Custom/Execute")
		// Request JSON data in response
		.WithContentType(ContentType.Json)
		// POST request, with defined types to (de)serialize req/resp data
		.Post<LocalProcedureRequest, List<OrderInfo>>
		(localProcedureRequest)
		.ResponseObject;

	@*
	// Uncomment to see JSON response data in the HTML Template editor
	<pre>
		@Raw(Newtonsoft.Json.JsonConvert.SerializeObject(
			@orders,
			Newtonsoft.Json.Formatting.Indented
		));
	</pre>
	*@
}

@if (orders.Count > 0)
{
	<h1>Customer Orders</h1>

	<ul>
		@foreach (var order in orders)
		{
			<li>
				@order.OrderNo -
				@order.OrderTotal.ToString("C") -
				@order.LastUpdate.ToString("dd MMMM yyyy HH:mm tt")
			</li>
		}
	</ul>

	<p>
		TOTAL: @orders.Sum(o => o.OrderTotal).ToString("C")
	</p>
}

Tags: razor, REST API

Tips for writing HTML Templates

James Murty — Mon, 05 Dec 2022 05:04:30 GMT

Current Revision posted to Community Docs Wiki by James Murty on 12/5/2022 5:04:30 AM

Here are some tips for writing and managing HTML Templates in Tessitura. These tips work as of version 15.

Make your own backups

Tessitura does not create back-ups of HTML Templates, so you must do this yourself if you want to keep a history of changes and guard against accidentally breaking your emails.

Some advice:

Never edit an existing template directly. Instead, duplicate the original to a new name and work on it there. Copy your changes back into the original once you are sure they work
Make your own copies of template documents before – and during – the editing process by copying everything in the Template tab and pasting it somewhere else.
- If you have a version-controlled code repository this would be a perfect place to save copies of your templates and work-in-progress
- Even if you don't, saving your own copies of your templates before major changes is almost certainly a good idea.

Inspect contents of a Model or data object

Use the following snippet to show the contents of a data object in JSON format. This lets you find out what fields are available.

This example shows the contents of anObject. It works best if you wrap the statement in <pre></pre> tags.

<pre>
	@Raw(Newtonsoft.Json.JsonConvert.SerializeObject(
		@anObject,
		Newtonsoft.Json.Formatting.Indented
	));
</pre>

Tags: razor

Tips for writing HTML Templates

James Murty — Mon, 05 Dec 2022 05:04:11 GMT

Revision 1 posted to Community Docs Wiki by James Murty on 12/5/2022 5:04:11 AM

Here are some tips for writing and managing HTML Templates in Tessitura. These tips work as of version 15.

Make your own backups

Tessitura does not create back-ups of HTML Templates, so you must do this yourself if you want to keep a history of changes and guard against accidentally breaking your emails.

Some advice:

Never edit an existing template directly. Instead, duplicate the original to a new name and work on it there. Copy your changes back into the original once you are sure they work
Make your own copies of template documents before – and during – the editing process by copying everything in the Template tab and pasting it somewhere else.
- If you have a version-controlled code repository this would be a perfect place to save copies of your templates and work-in-progress
- Even if you don't, saving your own copies of your templates before major changes is almost certainly a good idea.

Inspect contents of a Model or data object

Use the following snippet to show the contents of a data object in JSON format. This lets you find out what fields are available.

This example shows the contents of anObject. It works best if you wrap the statement in <pre></pre> tags.

<pre>
	@Raw(Newtonsoft.Json.JsonConvert.SerializeObject(
		@anObject,
		Newtonsoft.Json.Formatting.Indented
	));
</pre>

Tags: razor

HTML Templates

James Murty — Mon, 05 Dec 2022 04:50:15 GMT

Current Revision posted to Community Docs Wiki by James Murty on 12/5/2022 4:50:15 AM

See sub-pages in the sidebar

Deploying network ticket printers via Windows Group Policy

Nick Reilingh — Sat, 02 Jul 2022 00:42:30 GMT

Current Revision posted to Community Docs Wiki by Nick Reilingh on 7/2/2022 12:42:30 AM

Printer deployment is a vast subject with a multitude of options, but I wanted to point out one particular footgun that can cause issues for box office personnel doing batch printing and similar activities:

When deploying networked ticket printers via Group Policy Preferences, an "action" must be selected for the preference from Create, Update, Replace, and Delete. This action controls how the preference will be applied. What may not be obvious if you are new to Group Policy is that the Replace action is equivalent to a Create action followed by a Delete action which is pre-scheduled for the next policy refresh. This means that every 90 minutes or so (with some random variance) when group policy is applied by the client, your printer will be deleted and immediately recreated by the group policy client.

If Tessitura is actively printing to a printer like in a batch print and the printer gets deleted, its reference to the printer is invalidated and the print will start to error out. This is because the reference to the printer during printing is a code object reference, not a reference by printer name, and when group policy deletes and recreates the printer, it deletes the existing code object and creates a brand new one that only just happens to have the same user-visible name.

So: Don't use the Replace action for ticket printers. Use Create or Update. You can always issue a Delete action preference later to clean up cruft instead of making use of the "Remove this item when it is no longer applied" option, which requires the Replace action.

Tags: printers, group policy

The Secret Life of HTML Templates

Nick Reilingh — Fri, 28 May 2021 16:03:36 GMT

Revision 6 posted to Community Docs Wiki by Nick Reilingh on 5/28/2021 4:03:36 PM

or: How I Learned to Stop Worrying and Just Write HTML Templates

or: HTML Templates: The Missing Manual

or: The HTML Templates documentation they don't want you to know about!

The Big Secret

Assorted Syntactic Tips and Tricks

@functions {
    private string SOME_URL_CONSTANT = "https://example.com";
    private string LinkTag(string link) {
        return "<a href=\"" + SOME_URL_CONSTANT + "\">" + link + "</a>";
    }
}
@Raw(LinkTag("some text"))
@* Outputs:
<a href="https://example.com">some text</a>
*@

Methods are private because the template's execution is just another method in the same class.

@helper BoldMe(string content) {
    <b>@content</b>
}
@BoldMe("look at me, I'm bold!")
@* Outputs:
<b>look at me, I&#39;m bold!</b>
*@

The output of the helper correctly writes literal or encoded HTML like the rest of the template does.

@functions {
    private void DIYRenderFunction(string content) {
        WriteLiteral("<p>");
        Write(content);
        WriteLiteral("</p>");
    }
}
@{ DIYRenderFunction("here are my paragraph tags & encoded content"); }
@* Outputs:
<p>here are my paragraph tags &amp; encoded content</p>
*@

@helper ItalicizeMe(dynamic content) {
    <i>@content</i>
}
@helper BoldMe(dynamic content) {
    <b>@content</b>
}
@ItalicizeMe(BoldMe("I'm bold, AND italic!"))
@ItalicizeMe("I'm only italic!")
@* Outputs:
    <i>    <b>I&#39;m bold, AND italic!</b>
</i>
    <i>I&#39;m only italic!</i>
*@

A special syntax exists in Razor 3 for raw text. This is necessary when using helpers without surrounding tags. Information here: ASP.NET MVC 3: Razor’s @: and <text> syntax

Now, with all of these tools in our toolbox, only one question remains... Can we avoid writing inline styles?

Tags: c#, HTML Templates, razor

The Secret Life of HTML Templates

Nick Reilingh — Fri, 28 May 2021 15:04:13 GMT

Revision 5 posted to Community Docs Wiki by Nick Reilingh on 5/28/2021 3:04:13 PM

or: How I Learned to Stop Worrying and Just Write HTML Templates

or: HTML Templates: The Missing Manual

or: The HTML Templates documentation they don't want you to know about!

The Big Secret

Assorted Syntactic Tips and Tricks

@functions {
    private string SOME_URL_CONSTANT = "https://example.com";
    private string LinkTag(string link) {
        return "<a href=\"" + SOME_URL_CONSTANT + "\">" + link + "</a>";
    }
}
@Raw(LinkTag("some text"))
@* Outputs:
<a href="https://example.com">some text</a>
*@

Methods are private because the template's execution is just another method in the same class.

@helper BoldMe(string content) {
    <b>@content</b>
}
@BoldMe("look at me, I'm bold!")
@* Outputs:
<b>look at me, I&#39;m bold!</b>
*@

The output of the helper correctly writes literal or encoded HTML like the rest of the template does.

@functions {
    private void DIYRenderFunction(string content) {
        WriteLiteral("<p>");
        Write(content);
        WriteLiteral("</p>");
    }
}
@{ DIYRenderFunction("here are my paragraph tags & encoded content"); }
@* Outputs:
<p>here are my paragraph tags &amp; encoded content</p>
*@

@helper ItalicizeMe(dynamic content) {
    <i>@content</i>
}
@helper BoldMe(dynamic content) {
    <b>@content</b>
}
@ItalicizeMe(BoldMe("I'm bold, AND italic!"))
@ItalicizeMe("I'm only italic!")
@* Outputs:
    <i>    <b>I&#39;m bold, AND italic!</b>
</i>
    <i>I&#39;m only italic!</i>
*@

A special syntax exists in Razor 3 for raw text. This is necessary when using helpers without surrounding tags. Information here: ASP.NET MVC 3: Razor’s @: and <text> syntax

Now, with all of these tools in our toolbox, only one question remains... Can we avoid writing inline styles?

Tags: c#, HTML Templates, razor

The Secret Life of HTML Templates

Nick Reilingh — Fri, 28 May 2021 04:31:56 GMT

Revision 4 posted to Community Docs Wiki by Nick Reilingh on 5/28/2021 4:31:56 AM

or: How I Learned to Stop Worrying and Just Write HTML Templates

or: HTML Templates: The Missing Manual

or: The HTML Templates documentation they don't want you to know about!

The Big Secret

Assorted Syntactic Tips and Tricks

The version of C# available in Tessitura HTML Templates in Tessitura V15.1 is C# 5.0. In Tessitura V16 there is support for interpolated strings, which indicates that the language has been updated to at least C# 6.0.

@functions {
    private string SOME_URL_CONSTANT = "https://example.com";
    private string LinkTag(string link) {
        return "<a href=\"" + SOME_URL_CONSTANT + "\">" + link + "</a>";
    }
}
@Raw(LinkTag("some text"))
@* Outputs:
<a href="https://example.com">some text</a>
*@

Methods are private because the template's execution is just another method in the same class.

@helper BoldMe(string content) {
    <b>@content</b>
}
@BoldMe("look at me, I'm bold!")
@* Outputs:
<b>look at me, I&#39;m bold!</b>
*@

The output of the helper correctly writes literal or encoded HTML like the rest of the template does.

@functions {
    private void DIYRenderFunction(string content) {
        WriteLiteral("<p>");
        Write(content);
        WriteLiteral("</p>");
    }
}
@{ DIYRenderFunction("here are my paragraph tags & encoded content"); }
@* Outputs:
<p>here are my paragraph tags &amp; encoded content</p>
*@

Helpers can be nested by calling .ToString() on the result of the inner helper before passing to the outer. Note that if the inner helper outputs HTML, then you will need to @Raw() it in the outer helper.

@helper ListMe(string content) {
    <ul>
        <li>@Raw(content)</li>
    </ul>
}
@helper BoldMe(string content) {
    <b>@content</b>
}
@ListMe(BoldMe("I am bold, AND in a list!").ToString())
@* Outputs:
    <ul>
        <li>    <b>I am bold, AND in a list!</b>
</li>
    </ul>
*@

A special syntax exists in Razor 3 for raw text. This is necessary when using helpers without surrounding tags. Information here: ASP.NET MVC 3: Razor’s @: and <text> syntax

Now, with all of these tools in our toolbox, only one question remains... Can we avoid writing inline styles?

Tags: c#, HTML Templates, razor

Transitioning TNEW Customizations to V16

Nick Reilingh — Fri, 28 May 2021 04:26:14 GMT

Current Revision posted to Community Docs Wiki by Nick Reilingh on 5/28/2021 4:26:14 AM

As of April 30, 2021, version 16 of Tessitura and TNEW are announced and (at least Tessitura is) in internal alpha testing. Closed beta is expected to occur in Q3 of the calendar year.

As of May 28, 2021, everything on this page is superseded by information in the May 2021 Open Studio (45:30).

TNEW Customizations (by which we mean database procedures which are invoked by hooks and URL routes inside the TNEW application) may be affected by changes in v16 in a few important ways:

The LWP_VALIDATE_CART execution path will be deprecated (or removed? currently unconfirmed.)
The legacy SOAP API is being removed, which will affect any customizations currently making use of the "TNEWSqlBridge" CLR procedures which are used to invoke SOAP methods from within a database procedure.

The usage of LWP_VALIDATE_CART will be replaced by a local procedure execution path for the same hooks. This means that in LTR_VALIDATE_CART, where you enable validation point hooks for various TNEW events, you will instead identify a local procedure to be invoked in place of LWP_VALIDATE_CART for each hook. In theory, this does not represent a loss in functionality, but more research is necessary to discover the best practices for refactoring existing LWP_VALIDATE_CART functionality into individual procedures. (Possibly this could be accomplished with some kind of wrapper procedure that reuses LWP_VALIDATE_CART, but many customizations use extended validation point logic that would require some changed URLs and other methods of invocation.)

The SOAP API removal represents a much more impactful change for those customizations that leverage the TNEWSqlBridge CLR procedures. At present, the next-generation answer to this has not yet been implemented, but it does remain in scope for V16's general release, and some preliminary design intentions do exist: TNEW will provide for something akin to a webhook infrastructure, where the same validation points that exist with precart can now invoke an external web service, which presumably will be provided with some context about the session such that it can easily make API calls back to the services with session context. It is recommended to wait for this feature to be implemented and fleshed out before rebuilding customizations that currently use the CLR procedures for v16.

New development happening today against v15.1 does not have many good options, in the event that bridging to the services layer is necessary from within a TNEW customization. If you build using the CLR procedures, you will just have to rearchitect the customization as a web service when v16 is available. The only way to avoid this while staying inside the database is to instead make calls to the REST services using OLE Automation, which tends to be very delicate and challenging code.

Tags: tnew customization, tnew, v16