Email variables list - OJS 3

lsteele · September 24, 2018, 10:56am

Is there a list of email variables available anywhere in the system? has anyone created it?
Thanks!
Lucia

astevens · October 1, 2018, 7:02pm

Unfortunately there is not a list of variables used in email templates. Most users determine the variables by opening other email templates. For example, if you open the Review Request Remind templates you’ll find the variable {$responseDueDate} and {$reviewDueDate}.

You can also look at the classes/mail/ArticleMailTemplate.inc.php and classes/mail/MailTemplate.inc.php files.

Best,
Amanda Stevens
Public Knowledge Project Team

lsteele · October 16, 2018, 9:33am

I would like to create one… is there a description of the contents pulled in by the individual variable? for example {$postInfo} which you find in paypal investigate payment email, can it be used elsewhere? Not sure I am clear enough…
Thanks Amanda

astevens · October 18, 2018, 8:17pm

Hi @lsteele,

It would be great to have you create a list! Thank you for the offer. I’m not completely clear on what information you’re looking for. Can you explain more?

Thanks,
Amanda Stevens
Public Knowledge Project Team

lsteele · October 19, 2018, 7:07pm

Hi Amanda,

basically a simple list which describes when a merge field (variable) will be correctly pulled in. From my experience, which is quite limited I admit, some variables do not seem to populate. I share a couple of examples below.

This is the same letter sent at different stages in the review process.

As I said, I am still on the learning curve for this and I imagine there is a lot more than meets the eye. However, a list of varibles could be useful. Here is my existing list:

Variable merge field

Description

{$contextName}

Journal’s full name

{$contextUrl}

Journal’s external (public) URL to access the OJS site

{$submissionUrl}

Submission URL

{$participantUsername}

Username of recipient

{$editorialContactSignature}

Inserts the Sender’s name

{$submissionId}

Sequential submission number

{$userFullName}

??

{$username}

??

{$password}

??

{$principalContactSignature}

Main contact of journal (EIC)

{$submitterName}

?? Corresponding author

{$editorialContactName}

Recipient

{$submissionTitle}

Full title of the manuscript

{$submissionAbstract}

{$submissionReviewUrl}

{$reviewDueDate}

{$responseDueDate}

{$reviewerName}

{$siteTitle}

{$rawCitation}

{$itemName}

{$itemCost} ({$itemCurrencyCode})

I add to the list as I come across new variables and once I know how they work I add a short description, but I am sure there are rules applied to the variables.

I am happy to build this list to share with everyone, if you think it could be useful.

Thanks, Amanda, it is great to know you are there…

Lucia

astevens · October 23, 2018, 12:07pm

Thanks, @lsteele. I will ask someone from our development team to step in and give you some more information about the variables, as I don’t know myself. The PKP user community will be happy to have this resource!

Best,
Amanda Stevens
Public Knowledge Project Team

NateWr · October 23, 2018, 1:07pm

Hi @lsteele,

As you’ve discovered, there isn’t one universal list of email variables. Each template is served a set of variables that are specific to that template’s purpose. For example, {$reviewerName} is only going to be available in the email templates for review assignments.

Having a glossary of email variables is a common request and there’s an issue filed in our development repository.

If you’re comfortable looking at code, you will find a few almost-universal templates that are added to every mail template here:

github.com

pkp/pkp-lib/blob/main/classes/mail/MailTemplate.inc.php#L138-L176


 *
 * @return boolean
 */
public function getAddressFieldsEnabled()
{
    return $this->addressFieldsEnabled;
}

/**
 * Check whether or not there were errors in the user input for this form.
 *
 * @return boolean true iff one or more error messages are stored.
 */
public function hasErrors()
{
    return ($this->errorMessages != null);
}

/**
 * Assigns values to e-mail parameters.

This file has been truncated. show original

That shows the following:

siteTitle is always available
principalContactSignature is always available but must be configured in the site or journal settings
contextName and contextUrl are available if the email template is specific to a journal (this will be most of them). “context” is what we call a journal in OJS and a press in OMP.
senderEmail and senderName are available if there is a logged-in user making the request to send the email.

If you do a text search of the full source code for assignParams(, you’ll find 47 different instances where unique params are passed to different email templates. It will take some work, but collating that information would be useful.

We haven’t done this ourselves because this information may change with each release. If we were to provide documentation for each version, we’d need some way to generate this documentation automatically. We’d be very happy for help from the community in this regard.

lsteele · October 23, 2018, 1:04pm

Sounds good…. I am looking forward to producing a nice list…

Regards,

Lucia

lsteele · October 23, 2018, 7:14pm

Hello Nate,
thank you for your reply. I am not so clever as to read code… unfortunately. This is beyond me.
I am not sure if I can help, but it would be really good to know when a variable will work, that is in which context.

Do you maybe know what the sender and recipient actually mean in templates (see screenshot attached)?

It does not make sense, really, as I run an open access journal with no subscriptions…
Thanks fo ryour help!
Lucia

NateWr · October 25, 2018, 9:56am

Hi @lsteele,

In some cases, such as an automated email, the email will always come from a certain role and be sent to a certain role. However, looking at the list, it appears that a bunch of the roles described are incorrect.

This has probably escaped attention because it doesn’t effect the actual emails that are sent.

I found an existing issue filed that describes this problem:

https://github.com/pkp/pkp-lib/issues/2724

I’ve switched that issue from Enhancement to Bug, and I see it’s part of our Emails/Notifications project, so it is not likely to get lost.

lsteele · October 25, 2018, 1:47pm

Sounds good: I am not so clever and experienced with coding etc, but I am sure I will learn at least the basics along the way.
Thanks Nate!

fgnievinski · October 20, 2019, 5:08am

Here’s a related question:

FGN

Spaik · February 24, 2021, 10:02am

Hi, Amanda!
Is there a variable for given name of author?
@authorName contains both given name and family name.

astevens · March 4, 2021, 12:53am

Hi @Spaik,

I’m not aware of there being a variable for only the given name of the author. I did a search for $givenname in the email locale files and the code files where the variables are named and I didn’t find anything.

Best,
Amanda Stevens
Public Knowledge Project Team

Spaik · March 4, 2021, 7:12am

Hi, @astevens
Amanda, thank you for your job!