Insert sign order

The InsertOrder message has these main elements:

• Documents
• Attachments
• Merchant
• Signers
• Organizations
• WebContexts
• ExecutionDetails
• MetaData
• B2BPostProcessing
• PostProcessing
• CustomProperties

InsertOrder

The InsertOrder message is the message used place sign orders to E-Signing. This message must be used to initiate a signing. The first part of this page gives an overview of the main components of the structure in this message.

Back to top

​​​Doc​​uments​​

All documents to be signed are defined in this part of the sign order. The sign order must consist of at least one document in either TEXT, PDF or XML format. Each document can be up to 10 MB Base64 encoded while the sign order can be up to 30 MB Base64 encoded. Encoded documents add approximately 30 % extra to a non-encoded document. Any restrictions on the document sizes related to the specific eID are specified in the eID section.

Note: It is always adviced to try testing the different documents used in the customer test environment. Larger documents may degrade the user experience. If possible, try avoiding a large amount of graphics in the document.

PDF Forms

The PDF sent to E-Signing can either be a regular PDF or a PDF form, but shouldn't be a secured PDF. The PDF form must be filled out by the first signer of the document. Other signers will sign the fulfilled document. Note: The first signer of a PDF form can't be a MerchantSigner, but must be a real person.

The PDF form in E-Signing support these form elements: 

• Single-line text
• Multi-line text
• Dropdown
• Radio button
• Check box

Selected text elements and dropdowns will be shown as an overlay. This increases the readability and usage on smaller devices. Here is an example of how the overlay look:

The user may use keyboard navigation to navigate in the document:

• Tab - can be used to move from element to element
• Space - can be used to change values for radio buttons and check boxes
• ESC - closing overlays
• Enter - apply values to single-line text

The service is currently only validating required fields. User will not be able to proceed without filling these. Other validation is currently not supported.

The form data inserted by the first signer can be retrieve using the GetFormData request. The data will be returned as name/value pairs, and the name will be retrieved from the input form field name. The different form fields should be named uniquely.

We recommend that all PDF form document templates is tested in Nets customer test environment prior to use in production to make sure they can be filled out and signed correctly.

Note: The use of this function may have an extra cost. If it is not already priced in your agreement, please contact sales.esecurity@nets.eu to retrieve the price list and an offer. 

Back to top

Attachments

One or more attachments can be added to a sign order and displayed to a specified signer during the signing flow. The attachments must be PDF documents. The attachments are displayed as links above the sign client, and the links will open in a PDF reader or another browser window. The attachments are not signed and will not be a part of the SDO or PAdES document. Below is an example on how it will look like. Note: You might need to increase the height of the iframe used:

​​Merchant

An E-Signing customer may request to get notifications on events related to a sign order. The Merchant structure defines the notification channels and triggers for the customer.

NotificationChannel

​Back to top

​Signers​

There are two types of signers in E-Signing: either a physical person (an end user) or an organisation (the E-Signing customer). The organisation signature is done automatically in E-Signing using the customer's organisational certificate of choice. The end user signer can be presented with either a specific eID or a list of all available eIDs.

​​​​EndUserSigner​

This element defines the physical signer of a document - the end user. The end user is primarily referred to as the signer.

​​AcceptedPKIs​

This element defines the different eID(s) the signer can use when signing a document.

BankID

This element is used to defined that the signer can sign with BankID (NO).

BankIDNOMobile

This element is used to defined that the signer can sign with BankID on mobile (NO).

NemID

This element is used to defined that the signer can sign with NemID JS (DK).

BankIDSE

This element is used to defined that the signer can sign with BankID (SE).

NemID-OpenSign

This element is used to defined that the signer can sign with the NemID CodeFile client (DK). The NemID CodeFile client has replaced the OpenSign applet.

PKI-OTP

This element is used to defined that the signer can sign with an OTP eID. This element currently only support customer specific eIDs.

Nets

This element is used to define that the signer can sign based on an authentication. The AuthenticationID is used to specify the authentication method that the end user can authenticate with.

Read for more information about authentication-based signing.

MitID

This element is used to defined that the signer can sign with MitID through the NemLog-in broker. 

NotificationChannel

This element is used to define a specific notification channel related to a signer.

​​MerchantSigner​

The MerchantSigner element specifies if the customer's organisation signature shall be applied. The signing is performed with one of the customer's eIDs hosted by E-Signing.

Back to top

Organizations​​

A set of organisations can be defined in this element. These will be a part of the sign and procura validation in the B2BPostProcessing element or it can be used with the Private NemID - on behalf of a company​ function​.

Back to top

​WebContexts

The WebContexts element defines a set of URLs that tells E-Signing where a signer is supposed to perform the sign process and where a signer shall be routed when he/she has signed, if an error occur or if he/she cancels the signing. After inserting the sign order, the E-Signing customer may retrieve a sign URL using the GetSigningProcesses message. This URL is a pointer to a sign process involving a signer and a document. The customer chooses how the sign experience shall be by either presenting the sign proccess embedded on its own sign page or redirects the signer to a standalone Nets page. The sign URL can also be distributed to signers via notification channels. If a signer is registered with the e-mail channel and the trigger OnSignProcessReady  set, the signer will receive an e-mail holding the sign URL when it is his/hers turn to sign.

The SignURLBase is the sign URL prefix. When a sign order is inserted into E-Signing the WebContext is registered for later use. When a customer asks for the sign URL, E-Signing generates a unique reference and appends it to the end of the SignURLBase. Sign URL = SignURLBase + <generated reference>.

Note: All of the below URLs can be overridden by parameters added to the sign URL when presenting the URL for the signer. 

Back to top

ExecutionDetails​

Execution details are a set of rules that the E-Signing customer wishes to impose on the sign order. These can be used to specify the following aspects of signing:

• Outline which documents are assigned to the different signers.
• The order in which documents are signed. E-Signing allows for parallel, sequencial or a combination of both. Read more about the sign workflow.
• A deadline before which documents must be signed. Each document and signer can be specified with a deadline.
• Validity period of a sign URL (whether they are for multiple or single use)

Steps

The Steps element contains one or more Step element that again can hold a set of SigningProcess elements. See the definitions of steps and sign processes here.

Back to top

MetaData​

The MetaData structure enables the customer to set its own “labels” on this sign order.

Reserved metadat​a​​

Back to top

B2BPostProcessing​

The B2BPostProcessing structure are used to define the mapping between organizations, documents and the signers that will be included in a sign and procura verification. The sign and procura verification are using the Nets ID-Rights service.

Back to top

PostProcessing​​

The PostProcessing element includes functions that are processed after all signatures in a sign order have been performed. This includes archival to the Nets E-Archive and other customer specific archives.

Archive

When archiving to the Nets E-Archive through E-Signing, there are some general indexes that must be set by the customers and some indexes that are set by the E-Signing service. In addition, the customer may set their own indexes. The indexes that are required set by the customer and the ones set by E-Signing are listed in the table below. Other customer specific indexes are not added here, and the customer should check their E-Archive settings to find information about those.

<PostProcessing>
  <ArchiveDefinitions>
    <Archive>
      <ArchiveName>eArchive</ArchiveName>
      <ObjectRef>
        <LocalDocumentReference>text1</LocalDocumentReference>
      </ObjectRef>
      <ArchiveData>
        <Index>
          <Key>indexname1</Key>
          <Value>indexvalue1</Value>
        </Index>
        <Index>
          <Key>indexname2</Key>
          <Value>indexvalue2</Value>
        </Index>
        <Index>
          <Key>indexname3</Key>
          <Value>indexvalue3</Value>
        </Index>    
     </ArchiveData>
      <MetaDataList>
        <MetaData>
          <Key>orgNumber</Key>
          <Value>999888777</Value>
        </MetaData>
        <MetaData>
          <Key>subArchiveName</Key>
          <Value>documents</Value>
        </MetaData>
      </MetaDataList>
    </Archive>
  </ArchiveDefinitions>
</PostProcessing>

Back to top

CustomProperties

A set of additional data related to one or all signers can be defined in this element. The properties will be add to the SDO as an extra signature on the document. There is no validation of the data in the CustomProperties, and these are returned in the SDO as they were specified in the sign order. 

Note: CustomProperties can't be used if the OutputFormat is set to PAdES. 

Reserved property name

There are some Name values that are reserved.

How will this look like in the SDO?:

Note: If the SignatureRef value is set this refers to a specific signer. This will be the case if the LocalSignerReference is used. If the SignatureRef is set to [1] this refers to the first signature in the SDO, if set to [2] it refers to the second signature and so on.

<AdditionalSignatureProperties xmlns="http://www.nets.eu/e-signing/additional-signature-properties" CreateTime="2019-05-23T16:40:32.956+00:00" Version="1.0">
	<CustomProperties DocumentDigest="2.16.840.1.101.3.4.2.1:j/9pWQJlux2wUDW1+cNvDV3xX2g7GnSdbrGH+Ycjr3E=">
		<Properties SignatureDigest="2.16.840.1.101.3.4.2.1:HHTvf/+w4LK2f/cZ06gIqTDD8dfBncn3DtJmJC9xPG8=" SignatureRef="(//sdo:SignatureElement)[1]">
			<Property name="OrganisationNumber">123456789</Property> 
			<Property name="casenumber">123456789</Property> 
		</Properties>
	</CustomProperties>
</AdditionalSignatureProperties>

Back to top 

InsertOrder response