Steps for additional first-time customization

You need to perform these steps only if you are customizing certificate templates for the first time. If your company used an earlier release of PKI Services, you do not need to perform these steps.

Perform the following steps if you want to perform additional customization of the end-user web pages:

Review the templates and decide which you need to update.
_______________________________________________________________
If necessary, change the true name, alias, or nickname, as in the following lines.
```
<TEMPLATE NAME=true_name>
<TEMPLATE NAME=alias>
<NICKNAME=nickname>
```
true_name

Is the whole and complete name of the certificate template.

alias

Differentiates browser from server certificates. An alias is not required. You can have more than one alias.

nickname

Is an 8-character name. SAF certificates do not have nicknames. If a nickname is not present, the certificate is not automatically renewable.
Example:
```
<TEMPLATE NAME=1-Year PKI SSL Browser Certificate>
<TEMPLATE NAME=PKI Browser Certificate> 
<NICKNAME=1YBSSL>
```
_______________________________________________________________
If necessary, in the CONTENT subsection, change the certificate fields listed. The following example is from the one-year PKI SSL browser certificate template.
Example:
```
<p> Enter values for the following field(s)
 %%CommonName%%
 %%Requestor (optional)%%
 %%PassPhrase%%
 %%PublicKey2[browsertype]%% 
```
_______________________________________________________________
If you add required fields in the preceding step, update the JavaScript code that is part of the embedded HTML to check for required fields that are missing.
Example:
```
ValidCommonName(frm) &&
ValidPassPhrase(frm) &&
ValidPublicKey2(frm) &&
```
_______________________________________________________________
If necessary, in the APPL subsection, change the list of certificate fields that the application provides. (Currently, the only supported fields are UserId and HostIdMap.) The following example is from the two-year PKI browser certificate for authenticating to z/OS®:
Example:
```
<APPL>
 %%UserId%%
 %%HostIdMap=@host-name%%
</APPL>
```
_______________________________________________________________
If necessary, in the CONSTANT subsection, update the list of certificate fields whose values are hardcoded. The following example is from the one-year PKI SSL browser certificate template:
Example:
```
<CONSTANT>
 %%NotBefore=0%%
 %%NotAfter=365%%
 %%KeyUsage=handshake%%
 %%OrgUnit=Class 1 Internet Certificate CA%%
 %%Org=The Firm%%
 %%SignWith=PKI:%%
</CONSTANT>
```
Note: If you update the CONSTANT subsection to create subject distinguished names, make sure that the names match the LDAP suffix that are defined for your LDAP server. Otherwise, the certificates are not posted to LDAP. PKI Services constructs the subject distinguished name from the fields that are specified in the following order:
- CommonName
- Title
- OrgUnit (if repeating, in the order that they appear in the template file)
- Org
- Locality
- StateProv
- Country
_______________________________________________________________
If necessary, edit the ADMINAPPROVE subsection. (Certificates requiring an administrator's approval have an ADMINAPPROVE subsection. The absence of the ADMINAPPROVE subsection indicates auto-approval for requests.) Make sure the ADMINAPPROVE subsection, if present, correctly lists the minimum set of certificate fields that the administrator can change.
Note:
1. There might be more fields in the ADMINAPPROVE subsection than fields that the user can complete in the certificate request (because the users do not necessarily see all fields).
2. Do not include the Requestor, Label, UserId, PublicKey, or SignWith fields in the ADMINAPPROVE subsection. These fields cannot be changed and are ignored if present. (For a list of tags that are allowed in the ADMINAPPROVE subsection, see the subsection ADMINAPPROVE, in the topic about TEMPLATE sections.)
3. If a request is examined and approved by more than one PKI Services administrator, include the ADMINNUM=value tag in the ADMINAPPROVE subsection.
The following example of the ADMINAPPROVE subsection is from the one-year PKI SSL browser certificate template:
Example:
```
<ADMINAPPROVE>
 %%CommonName (Optional)%%
 %%OrgUnit (Optional)%%
 %%OrgUnit (Optional)%%
 %%Org (Optional)%%
 %%NotBefore (optional)%%
 %%NotAfter (Optional)%%
 %%KeyUsage (Optional)%%
 %%HostIdMap (Optional)%%
 %%HostIdMap (Optional)%%
 %%HostIdMap (Optional)%%
 %%HostIdMap (Optional)%%
</ADMINAPPROVE>
```
Note: The four %%HostIdMap%% lines in the example indicate that the approver can provide up to four HostIdMap entries.
_______________________________________________________________

If necessary, update the following subsections:

The SUCCESSCONTENT subsection contains only the %%-requestok%% named field, which contains the HTML for the web page whose main heading is "Request submitted successfully". To make changes to this web page, update the -requestok INSERT (in the INSERT section of pkiserv.tmpl):

<INSERT NAME=-requestok>
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
<HTML lang="en"><HEAD>
<TITLE> Web Based Certificate Generation Success</TITLE>
</HEAD>
<BODY>
<H1> Request submitted Successfully</H1>
[errorinfo]
<p> Here's your transaction ID. You will need it to retrieve your
certificate. Press 'Continue' to retrieve the certificate.
<p> <TABLE BORDER><TR><TD>[transactionid]</TD></TR></TABLE>
<FORM METHOD=GET ACTION="/PKIServ/ssl-cgi/caretrieve.rexx">
<INPUT NAME="Template" TYPE="hidden" VALUE="[tmplname]">
<INPUT NAME="TransactionId" TYPE="hidden" VALUE="[transactionid]">
<INPUT TYPE="submit" VALUE="Continue">
</FORM>
<p>%%-pagefooter%%
</BODY>
</HTML>
</INSERT>

The FAILURECONTENT subsection contains only the %%-requestbad%% named field, which contains the HTML for the web page whose main heading is "Request was not successful". To make changes to this web page, update the requestbad INSERT:

<INSERT NAME=-requestbad>
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
<HTML lang="en"><HEAD>
<TITLE> Web Based Certificate Generation Failure</TITLE>
</HEAD>
<BODY>
<H1> Request was not successful</H1>
<p> Please correct the problem or report the error to your Web admin
person<br>
<PRE>
[errorinfo]
</PRE>
<p>%%-pagefooter%%
</BODY>
</HTML>
</INSERT>

_______________________________________________________________

If necessary, update the RETRIEVECONTENT subsection.
Note: See Steps for changing the runtime user ID at retrieval for directions for changing the runtime user ID for retrieving a certificate.
1. The RETRIEVECONTENT subsection includes the %%-copyright%% named field. If you want to make any changes in the copyright statement, update the copyright INSERT. (The following sample is the copyright INSERT as it is originally provided in the pkiserv.tmpl file. You should have previously updated this INSERT by providing information tailored to your company, as described in Steps for performing minimal customization.)
```
<INSERT NAME=-copyright>
  </INSERT>
```
2. If necessary, update any web page content (such as headers, footers, titles, background colors, frames, links, and so on) for the web page whose main heading is "Retrieve Your (certificate template name)".
_______________________________________________________________
If you are updating the template for a server certificate, you can update the HTML in the RETURNCERT subsection to customize the returned web page. (For a browser template, you cannot change the RETURNCERT subsection. It must contain the %%returnbrowsercert%% named field, which contains the [browsertype] substitution variable. The INSERT section contains browser-specific returnbrowsercert INSERTs.)
_______________________________________________________________