← FlexAPI Documentation / Reference / Document Templates

Document Templates

A Document Template lets you send a document, or a set of documents, with its tasks and roles once, and have SIGNiX store it. You then import the template into new transactions, map your signers to its roles, and reuse the stored documents and fields without sending them again. Signers and tasks can be re-assigned for each transaction. Document Templates are not a separate method. You create and use them with SubmitDocument, using a few additional elements.

Before you start

  • Templates use SubmitDocument. There is no separate method. You create a template and use one with the same request.
  • A template works only within its own Sponsor and Client. A different Sponsor and Client pair cannot reference it.
  • Only SuspendOnStart transactions can import templates. The transaction that imports one must set SuspendOnStart to yes.
  • Keep three things when you create a template. You need them to use it later: the DocumentSetID of the template, the RefID or RoleName of each party, and the RefID of each document.
  • A template can hold several documents. The documents are saved with the template. You import the template once, even if it has several documents.
  • The template's name is its DocSetDescription. The name is informational only.
  • Tasks can be edited after import. Use a GetAccessLink request for the submitter to edit the tasks in the new transaction.
  • Use the same CustInfo credentials as your other requests (Sponsor, Client, UserId and Pswd).

How it works

  1. Create the template. Submit a SuspendOnStart transaction with SaveAsTemplate set to yes. SIGNiX stores the documents, tasks and roles, and returns the template's DocumentSetID.
  2. Import it. In a new SuspendOnStart transaction, list the templates to use in ImportTransactionTemplates. Then map each of your signers to the template's roles with PlaysRoleMap.
  3. Use its documents. Add a Form with a TransactionTemplateForm for each document you want from the template. You can use the document as it is, or replace it with a new one and keep its fields.

The sample below shows where each new element goes. SaveAsTemplate is used when creating a template. The other elements are used when importing one.

Where the Document Template elements go in SubmitDocument
<!-- A SubmitDocument request, showing only the elements that matter here. -->
<Data>

  <!-- Required for a template to be created or imported. -->
  <SuspendOnStart>yes</SuspendOnStart>

  <!-- Creating a template: goes right after SuspendOnStart. -->
  <SaveAsTemplate>yes</SaveAsTemplate>

  <!-- Importing templates: goes right before the first MemberInfo. -->
  <ImportTransactionTemplates>
    <TransactionTemplate>
      <RefID>YOUR_TEMPLATE_REF_ID</RefID>
      <DocumentSetID>YOUR_TEMPLATE_DOCUMENT_SET_ID</DocumentSetID>
    </TransactionTemplate>
  </ImportTransactionTemplates>

  <MemberInfo>
    <RefID>YOUR_SIGNER_REF_ID</RefID>

    <!-- Importing templates: goes between RefID and WorkflowOrder. -->
    <PlaysRoleMap>
      <PlaysRole>
        <TemplateRefId>YOUR_TEMPLATE_REF_ID</TemplateRefId>
        <RoleRefId>YOUR_ROLE</RoleRefId>
      </PlaysRole>
    </PlaysRoleMap>

    <WorkflowOrder>1</WorkflowOrder>
    <!-- ... the other MemberInfo elements ... -->
  </MemberInfo>

  <Form>
    <!-- Importing templates: identifies a document in an imported template. -->
    <TransactionTemplateForm>
      <TemplateRefId>YOUR_TEMPLATE_REF_ID</TemplateRefId>
      <DocumentRefId>YOUR_DOCUMENT_REF_ID</DocumentRefId>
    </TransactionTemplateForm>
  </Form>

</Data>

Create a template

Creating a template is the same as submitting a SuspendOnStart transaction, with two differences.

  1. SaveAsTemplate. A new element that takes yes or no and defaults to no. When it is yes, the transaction is saved as a Document Template. It goes right after SuspendOnStart.
  2. A smaller MemberInfo. The only required element is RefID. You can also add an optional RoleName. If you leave out RoleName, the RefID is used as the role name. Any other MemberInfo data you send is never used, because the values are overwritten by the SubmitDocument request that imports the template. RoleName can also be used in regular SubmitDocument requests.

The response is the DocumentSetID of the new template, the same as the response to a SuspendOnStart SubmitDocument request. The documents are saved with the template. The template's name is the DocSetDescription, which is informational only.

Creating your first template

  1. Add <SaveAsTemplate>yes</SaveAsTemplate> after SuspendOnStart.
  2. Remove all the child elements of each MemberInfo except RefID (and RoleName, if you use it).
  3. Submit the request.
  4. Save the returned DocumentSetID, the RefID or RoleName of each MemberInfo, and the RefID of each Form. You need all of them to use the template.
Create a Document Template - annotated request
<?xml version="1.0" ?>
<SubmitDocumentRq xmlns="urn:com:signix:schema:sdddc-1-1">

  <CustInfo>
    <Sponsor>YOUR_SPONSOR</Sponsor>
    <Client>YOUR_CLIENT</Client>
    <UserId>YOUR_USER</UserId>
    <Pswd>YOUR_PASSWORD</Pswd>
    <Demo>yes</Demo> <!-- Required. yes for demo and test, no for a real transaction. -->
  </CustInfo>

  <Data>
    <TransactionID>YOUR_TRANSACTION_ID</TransactionID>

    <!-- The name of the template. Informational only. -->
    <DocSetDescription>YOUR_TEMPLATE_NAME</DocSetDescription>

    <SubmitterEmail>YOUR_SUBMITTER_EMAIL</SubmitterEmail>
    <SubmitterName>YOUR_SUBMITTER_NAME</SubmitterName>
    <DeliveryType>SDDDC</DeliveryType>
    <SuspendOnStart>yes</SuspendOnStart>

    <!-- Optional, defaults to no. yes saves this transaction as a Document Template.
         Goes right after SuspendOnStart. -->
    <SaveAsTemplate>yes</SaveAsTemplate>

    <!-- Only RefID is required in each MemberInfo. Anything else you send is not used. -->
    <MemberInfo>
      <RefID>YOUR_SIGNER1_REF_ID</RefID>
      <!-- Optional. The role name. If left out, the RefID is the role name. -->
      <RoleName>YOUR_SIGNER1_ROLE</RoleName>
    </MemberInfo>

    <MemberInfo>
      <RefID>YOUR_SIGNER2_REF_ID</RefID>
      <RoleName>YOUR_SIGNER2_ROLE</RoleName>
    </MemberInfo>

    <!-- One Form for each document in the template. Save each RefID: you need it to use the
         document later. -->
    <Form>
      <RefID>YOUR_DOCUMENT_REF_ID</RefID>
      <Desc>YOUR_DOCUMENT_DESCRIPTION</Desc>
      <FileName>YOUR_FILE_NAME.pdf</FileName>
      <MimeType>application/pdf</MimeType>

      <SignatureLine>
        <MemberInfoNumber>1</MemberInfoNumber>
        <SignField>YOUR_SIGNATURE_FIELD_1</SignField>
        <DateSignedField>YOUR_DATE_FIELD_1</DateSignedField>
        <DateSignedFormat>MM/dd/yy</DateSignedFormat>
      </SignatureLine>

      <SignatureLine>
        <MemberInfoNumber>2</MemberInfoNumber>
        <SignField>YOUR_SIGNATURE_FIELD_2</SignField>
        <DateSignedField>YOUR_DATE_FIELD_2</DateSignedField>
        <DateSignedFormat>MM/dd/yy</DateSignedFormat>
      </SignatureLine>

      <Length>PDF_BYTE_LENGTH</Length>
      <Data>BASE64_PDF</Data>
    </Form>
  </Data>

</SubmitDocumentRq>

Import a template

Only transactions with SuspendOnStart set to yes can use Document Templates. You can import one or more templates into a single transaction. Wrap all of them in a new ImportTransactionTemplates element, which goes in the SubmitDocument request right before the first MemberInfo.

  • TransactionTemplate. Occurs once for each template you import. If a template has several documents, you import it only once.
    • RefID. Required. SubmitDocument uses it to identify the template when it imports and copies fields, and you use it again when you map signers to roles. It must be unique within the transaction. For example, Template1 can be used only once in a request, but can be used by many requests.
    • DocumentSetID. Required. The DocumentSetID of the template you created.
ImportTransactionTemplates (before the first MemberInfo)
<!-- Goes right before the first MemberInfo. The transaction must have SuspendOnStart set to yes. -->
<ImportTransactionTemplates>

  <!-- Once for each template to import. -->
  <TransactionTemplate>
    <RefID>YOUR_TEMPLATE_1_REF_ID</RefID> <!-- Required. Unique within this request. -->
    <DocumentSetID>YOUR_TEMPLATE_1_DOCUMENT_SET_ID</DocumentSetID> <!-- Required. From when you created the template. -->
  </TransactionTemplate>

  <TransactionTemplate>
    <RefID>YOUR_TEMPLATE_2_REF_ID</RefID>
    <DocumentSetID>YOUR_TEMPLATE_2_DOCUMENT_SET_ID</DocumentSetID>
  </TransactionTemplate>

</ImportTransactionTemplates>

Map signers to roles

Next, map each signer in your MemberInfo elements to the roles defined in the templates. To do that you need to know the role name of each party when the template was created. That is the RoleName of its MemberInfo, or its RefID if it had no RoleName. Each signer can be mapped to one or more roles in each template. The new PlaysRoleMap element in MemberInfo does the mapping. It goes between the RefID and WorkflowOrder elements at the start of the MemberInfo.

  • PlaysRole. Maps the signer to one role in one imported template. You need one PlaysRole for each role the signer plays.
    • TemplateRefId. The RefID you gave the template in ImportTransactionTemplates. Do not confuse it with the RefID of the signer just above it.
    • RoleRefId. The role name from when the template was created.

In the first example below, the signer First Signer takes on the actions, tasks and fields of the Signer1 role in the Template1 template. If one signer plays several roles, even in the same template, there is still one PlaysRole for each role.

After the transaction is created, the submitter can still edit its tasks. Use a GetAccessLink request for the submitter.

PlaysRoleMap - one role, several roles, several templates
<!-- 1. One signer plays one role in one template. -->
<MemberInfo>
  <RefID>YOUR_SIGNER_REF_ID</RefID>
  <PlaysRoleMap>
    <PlaysRole>
      <TemplateRefId>YOUR_TEMPLATE_1_REF_ID</TemplateRefId> <!-- From ImportTransactionTemplates -->
      <RoleRefId>YOUR_ROLE_1</RoleRefId> <!-- The role name when the template was created -->
    </PlaysRole>
  </PlaysRoleMap>
  <WorkflowOrder>1</WorkflowOrder>
  <!-- ... the other MemberInfo elements ... -->
</MemberInfo>

<!-- 2. One signer plays two roles in the same template: one PlaysRole for each role. -->
<MemberInfo>
  <RefID>YOUR_SIGNER_REF_ID</RefID>
  <PlaysRoleMap>
    <PlaysRole>
      <TemplateRefId>YOUR_TEMPLATE_1_REF_ID</TemplateRefId>
      <RoleRefId>YOUR_ROLE_1</RoleRefId>
    </PlaysRole>
    <PlaysRole>
      <TemplateRefId>YOUR_TEMPLATE_1_REF_ID</TemplateRefId>
      <RoleRefId>YOUR_ROLE_2</RoleRefId>
    </PlaysRole>
  </PlaysRoleMap>
  <WorkflowOrder>1</WorkflowOrder>
  <!-- ... the other MemberInfo elements ... -->
</MemberInfo>

<!-- 3. One signer plays roles across two templates. -->
<MemberInfo>
  <RefID>YOUR_SIGNER_REF_ID</RefID>
  <PlaysRoleMap>
    <PlaysRole>
      <TemplateRefId>YOUR_TEMPLATE_1_REF_ID</TemplateRefId>
      <RoleRefId>YOUR_ROLE_1</RoleRefId>
    </PlaysRole>
    <PlaysRole>
      <TemplateRefId>YOUR_TEMPLATE_2_REF_ID</TemplateRefId>
      <RoleRefId>YOUR_ROLE_1</RoleRefId>
    </PlaysRole>
  </PlaysRoleMap>
  <WorkflowOrder>1</WorkflowOrder>
  <!-- ... the other MemberInfo elements ... -->
</MemberInfo>

Use the template's documents

There are two ways to use an imported template's documents. The first imports a whole document, with all its fields, from the template. Use it when the template already holds the document the transaction needs. The second copies the fields from a template document but replaces the document itself with a new one.

Both ways use the same Form element as SubmitDocument, with a new TransactionTemplateForm element inside it. You need one Form for each document you use from an imported template. If a template has several documents but you need only one, send one Form for that document. A Form can hold only one TransactionTemplateForm. To use another document or template, add another Form. You can also add documents that are not from any template, in their own Form elements, as you normally would.

  • TemplateRefId. The RefID you gave the template in ImportTransactionTemplates.
  • DocumentRefId. The RefID of the document's Form when the template was created.
  • IsReplacement. Optional, yes or no. With no, the whole document from the template is used. With yes, the document is replaced in this transaction with a new one. The default is no, so you can leave it out to use the template's document unchanged.

To reuse a document, send only the TransactionTemplateForm. None of the other Form elements are used. To replace a document, also send the RefID and the other usual Form elements. Replacing does not change the document in the template. The new document is used only in this transaction.

TransactionTemplateForm - reuse a document, or replace it
<!-- 1. Reuse a document in its entirety. Only TransactionTemplateForm is sent. -->
<Form>
  <TransactionTemplateForm>
    <TemplateRefId>YOUR_TEMPLATE_1_REF_ID</TemplateRefId>
    <DocumentRefId>YOUR_DOCUMENT_REF_ID</DocumentRefId>
  </TransactionTemplateForm>
</Form>

<!-- 2. The same, with IsReplacement stated. no is the default. -->
<Form>
  <TransactionTemplateForm>
    <TemplateRefId>YOUR_TEMPLATE_1_REF_ID</TemplateRefId>
    <DocumentRefId>YOUR_DOCUMENT_REF_ID</DocumentRefId>
    <IsReplacement>no</IsReplacement>
  </TransactionTemplateForm>
</Form>

<!-- 3. Copy the fields from the template document, but use a new document in this transaction.
        The document in the template is not changed. -->
<Form>
  <RefID>YOUR_REPLACEMENT_DOCUMENT_REF_ID</RefID>
  <TransactionTemplateForm>
    <TemplateRefId>YOUR_TEMPLATE_1_REF_ID</TemplateRefId>
    <DocumentRefId>YOUR_DOCUMENT_REF_ID</DocumentRefId>
    <IsReplacement>yes</IsReplacement>
  </TransactionTemplateForm>
  <Desc>YOUR_DOCUMENT_DESCRIPTION</Desc>
  <FileName>YOUR_FILE_NAME.pdf</FileName>
  <MimeType>application/pdf</MimeType>
  <Length>PDF_BYTE_LENGTH</Length>
  <Data>BASE64_PDF</Data>
</Form>

Complete request

This request puts it together. It imports one template, maps two signers to the template's two roles, reuses one document from the template, and adds one document that is not from any template. For the other elements of the request, see the annotated sample on the SubmitDocument page.

Complete request that imports a Document Template
<?xml version="1.0" ?>
<SubmitDocumentRq xmlns="urn:com:signix:schema:sdddc-1-1">

  <CustInfo>
    <Sponsor>YOUR_SPONSOR</Sponsor>
    <Client>YOUR_CLIENT</Client>
    <UserId>YOUR_USER</UserId>
    <Pswd>YOUR_PASSWORD</Pswd>
    <Demo>yes</Demo>
  </CustInfo>

  <Data>
    <TransactionID>YOUR_TRANSACTION_ID</TransactionID>
    <DocSetDescription>YOUR_TRANSACTION_TITLE</DocSetDescription>
    <SubmitterEmail>YOUR_SUBMITTER_EMAIL</SubmitterEmail>
    <SubmitterName>YOUR_SUBMITTER_NAME</SubmitterName>
    <DeliveryType>SDDDC</DeliveryType>

    <!-- Required to import a template. -->
    <SuspendOnStart>yes</SuspendOnStart>

    <!-- Right before the first MemberInfo. -->
    <ImportTransactionTemplates>
      <TransactionTemplate>
        <RefID>YOUR_TEMPLATE_REF_ID</RefID>
        <DocumentSetID>YOUR_TEMPLATE_DOCUMENT_SET_ID</DocumentSetID>
      </TransactionTemplate>
    </ImportTransactionTemplates>

    <MemberInfo> <!-- Signer 1 plays the first role in the template. -->
      <RefID>YOUR_SIGNER1_REF_ID</RefID>
      <PlaysRoleMap>
        <PlaysRole>
          <TemplateRefId>YOUR_TEMPLATE_REF_ID</TemplateRefId>
          <RoleRefId>YOUR_SIGNER1_ROLE</RoleRefId>
        </PlaysRole>
      </PlaysRoleMap>
      <WorkflowOrder>1</WorkflowOrder>
      <SSN>910000000</SSN>
      <DOB>00/00/0000</DOB>
      <FirstName>YOUR_FIRST_NAME_1</FirstName>
      <MiddleName></MiddleName>
      <LastName>YOUR_LAST_NAME_1</LastName>
      <Email>YOUR_SIGNER1_EMAIL</Email>
      <Service>SelectOneClick</Service>
    </MemberInfo>

    <MemberInfo> <!-- Signer 2 plays the second role in the template. -->
      <RefID>YOUR_SIGNER2_REF_ID</RefID>
      <PlaysRoleMap>
        <PlaysRole>
          <TemplateRefId>YOUR_TEMPLATE_REF_ID</TemplateRefId>
          <RoleRefId>YOUR_SIGNER2_ROLE</RoleRefId>
        </PlaysRole>
      </PlaysRoleMap>
      <WorkflowOrder>2</WorkflowOrder>
      <SSN>910000000</SSN>
      <DOB>00/00/0000</DOB>
      <FirstName>YOUR_FIRST_NAME_2</FirstName>
      <MiddleName></MiddleName>
      <LastName>YOUR_LAST_NAME_2</LastName>
      <Email>YOUR_SIGNER2_EMAIL</Email>
      <Service>SelectOneClick</Service>
    </MemberInfo>

    <!-- A document from the template, reused as it is. -->
    <Form>
      <TransactionTemplateForm>
        <TemplateRefId>YOUR_TEMPLATE_REF_ID</TemplateRefId>
        <DocumentRefId>YOUR_DOCUMENT_REF_ID</DocumentRefId>
      </TransactionTemplateForm>
    </Form>

    <!-- A document that is not from any template, as in a normal SubmitDocument request. -->
    <Form>
      <RefID>YOUR_EXTRA_DOCUMENT_REF_ID</RefID>
      <Desc>YOUR_EXTRA_DOCUMENT_DESCRIPTION</Desc>
      <FileName>YOUR_EXTRA_FILE_NAME.pdf</FileName>
      <MimeType>application/pdf</MimeType>
      <SignatureLine>
        <MemberInfoNumber>1</MemberInfoNumber>
        <SignField>YOUR_SIGNATURE_FIELD</SignField>
        <DateSignedField>YOUR_DATE_FIELD</DateSignedField>
        <DateSignedFormat>MM/dd/yy</DateSignedFormat>
      </SignatureLine>
      <Length>PDF_BYTE_LENGTH</Length>
      <Data>BASE64_PDF</Data>
    </Form>
  </Data>

</SubmitDocumentRq>

ReadyDox links

A ReadyDox link is a link to a transaction that you can share. The signer opens the link, enters their name and email address, and then completes the form. This lets a submitter create an online form without having to set the signer in advance. A template can be the form behind a ReadyDox link.

To add a ReadyDox link to a Document Template, create the template as described above, and add a UseReadyDox element right after SuspendOnStart, together with SaveAsTemplate.

  • CompanyName. Optional. Shown to the user when they open the ReadyDox link.
  • WelcomeMsg. Optional. A welcome message shown to the user when they open the ReadyDox link.

If you want all the defaults, send an empty UseReadyDox element.

The response contains only the DocumentSetID and the ReadyDox link, in ReadyDoxLink.

UseReadyDox (after SuspendOnStart)
<SuspendOnStart>yes</SuspendOnStart>
<SaveAsTemplate>yes</SaveAsTemplate>

<!-- Adds a ReadyDox link to the template. -->
<UseReadyDox>
  <CompanyName>YOUR_COMPANY_NAME</CompanyName> <!-- Optional. Shown when the link is opened. -->
  <WelcomeMsg>YOUR_WELCOME_MESSAGE</WelcomeMsg> <!-- Optional. Shown when the link is opened. -->
</UseReadyDox>

<!-- Or, to use all the defaults: -->
<!-- <UseReadyDox/> -->
Response with a ReadyDox link
<SubmitDocumentRs xmlns="urn:com:signix:schema:sdddc-1-1">

  <Status>
    <StatusCode>0</StatusCode>
    <StatusDesc>success</StatusDesc>
  </Status>

  <Data>
    <!-- The DocumentSetID of the template. -->
    <DocumentSetID>YOUR_DOCUMENT_SET_ID</DocumentSetID>

    <!-- The link to share. -->
    <ReadyDoxLink>YOUR_READYDOX_LINK</ReadyDoxLink>
  </Data>

</SubmitDocumentRs>

Error messages

If a SubmitDocument request that uses templates is missing required elements or has values that do not match, SIGNiX returns a non-zero StatusCode and a StatusDesc that describes the problem. See Status Codes on the main API page for the list of StatusCode values.

WhereWhat to check
TransactionTemplateEach one needs both a RefID and a DocumentSetID. A duplicate RefID returns SC_BAD_PARAMETER. A template that cannot be loaded returns a message in the form ImportTransactionTemplates: could not load DocumentSetId '…' for RefId '…'. Check that the template exists and belongs to the same Sponsor and Client. An empty or invalid template also returns an error.
TransactionTemplateFormEach one needs a TemplateRefId and a DocumentRefId. The TemplateRefId must match a RefID in ImportTransactionTemplates. The DocumentRefId must match the RefID of a document in that template, and the message lists the values it expects. Using a TransactionTemplateForm without an ImportTransactionTemplates element is also an error.
PlaysRoleEach one needs a TemplateRefId and a RoleRefId. The TemplateRefId must match a RefID in ImportTransactionTemplates. The RoleRefId must match a role in that template: the RoleName it was created with or, if it had none, the RefID. Each signature on an imported document must have exactly one matching PlaysRole.