Login
    Contents x
    Managing Custom Fields
    • 16 Oct 2024
    • 10 Minutes to read
    • Dark
      Light
    • PDF
    Contents

    Managing Custom Fields

    • Updated on 16 Oct 2024
    • 10 Minutes to read
    • Dark
      Light
    • PDF
    Article summary

    Java SDK.NET SDKREST API

    Java SDK

    To download the full code sample see our Code Share site.

    A Custom Field is one that, at the time of signing, is automatically populated with data that is specific to the signer. For instance, a signer might have an Agent Number, and that number may need to appear in the final document next to their signature. By using a custom field, the signer can specify their Agent Number, and that number will automatically appear in any other field that has been configured to receive it.

    The Custom Fields page enables you to manage the custom fields in your account.

    This functionality is available only if custom fields are enabled at the account level. Please contact our Support Team to have them enabled.

    Creating a Custom Field

    To create a custom field, you will need to build a CustomField object. Every custom field you create is identified by the unique id you set during this process. The following code will do this:

    Creating another custom field with the same id will overwrite the original custom field. Also, note that every custom field you create is done so for the entire account.

    String customFieldId1 = "policy_number_id";
CustomField customField = CustomFieldBuilder.customFieldWithId(customFieldId1)
    .withDefaultValue("123-456-789-0")
    .withTranslation(newTranslation("en")
        .withName("Policy Number")
        .withDescription("Car Insurance Policy Number."))
    .build();
eslClient.getCustomFieldService().createCustomField(customField);

    The withDefaultValue() is the value that appears after your signer has signed the document. This method is required when creating a custom field.

    Custom fields also contain a collection of translations which are used when displaying the custom field to account members.

    This tip is for accounts that support multiple languages. As a best practice, every custom field you need should be replicated for every language supported in your account. The system will only display the custom field in the language selected by the active user. If a custom field is not mapped to a language, it will default to English, regardless of the language selected by the active user.

    At least one translation is required when building your CustomField object. Use the OneSpan Sign CustomFieldService to create your custom field.

    Retrieving Custom Fields

    You can retrieve your custom fields with the OneSpan Sign CustomFieldService. You can either retrieve all custom fields, which are returned to you as a list, or retrieve a specific one using the custom field id. The following code will do this:

    // Get the entire list of custom fields from the account
List<CustomField> retrieveCustomFieldList1 = eslClient.getCustomFieldService().getCustomFields(Direction.ASCENDING);

// Get the first custom field from the account
CustomField retrieveCustomField = eslClient.getCustomFieldService().getCustomField(customFieldId1);

    Deleting a Custom Field

    Deleting a custom field from your account is also done with the OneSpan Sign CustomFieldService. The following code will do this:

    // Delete the second custom field from the account
eslClient.getCustomFieldService().deleteCustomField(customFieldId1);

    Editing a Signature Block to Add Custom Fields

    To edit signature block to add custom codes, use the following code. In this example, text anchors are used to position both signature and custom fields. For more information, see Text Anchors.

    .withSignature(signatureFor(email1)
    .withPositionAnchor(TextAnchorBuilder.newTextAnchor("Client Signature")
        .atPosition(TextAnchorPosition.TOPLEFT)
        .withOccurence(0)
        .withCharacter(16)
        .withSize(250, 70)
        .withOffset(20, -58))
    .withField(FieldBuilder.customField(customField.getId())
        .withPositionAnchor(TextAnchorBuilder.newTextAnchor("Policy Number")
            .atPosition(TextAnchorPosition.TOPLEFT)
            .withOccurence(0)
            .withCharacter(13)
            .withSize(250, 25)
            .withOffset(20, -10))))

    Results

    Once you have run your code, you will find your custom fields can be seen in your OneSpan Sign account. These custom fields will also be available for use in transactions. For more information, see Custom Fields.

    .NET SDK

    To download the full code sample see our Code Share site.

    A Custom Field is one that, at the time of signing, is automatically populated with data that is specific to the signer. For instance, a signer might have an Agent Number, and that number may need to appear in the final document next to their signature. By using a custom field, the signer can specify their Agent Number, and that number will automatically appear in any other field that has been configured to receive it.

    The Custom Fields page enables you to manage the custom fields in your account.

    This functionality is available only if custom fields are enabled at the account level. Please contact our Support Team to have them enabled.

    Creating a Custom Field

    To create a custom field, you will need to build a CustomField object. Every custom field you create is identified by the unique id you set during this process. The following code will do this:

    Creating another custom field with the same id will overwrite the original custom field. Also, note that every custom field you create is done so for the entire account.

    String customFieldId1 = "policy_number_id";
CustomField customField = CustomFieldBuilder.CustomFieldWithId(customFieldId1)
    .WithDefaultValue("123-456-789-0")
    .WithTranslation(TranslationBuilder.NewTranslation("en")
        .WithName("Policy Number")
        .WithDescription("Car Insurance Policy Number."))
    .Build();
eslClient.GetCustomFieldService().CreateCustomField(customField);

    The withDefaultValue() is the value that appears after your signer has signed the document. This method is required when creating a custom field.

    Custom fields also contain a collection of translations which are used when displaying the custom field to account members.

    This tip is for accounts that support multiple languages. As a best practice, every custom field you need should be replicated for every language supported in your account. The system will only display the custom field in the language selected by the active user. If a custom field is not mapped to a language, it will default to English, regardless of the language selected by the active user.

    At least one translation is required when building your CustomField object. Use the OneSpan Sign CustomFieldService to create your custom field.

    Retrieving Custom Fields

    You can retrieve your custom fields with theOneSpan Sign CustomFieldService. You can either retrieve all custom fields, which are returned to you as a list, or retrieve a specific one using the custom field id. The following code will do this:

    // Get the entire list of custom fields from the account
IList<CustomField> retrieveCustomFieldList1 = eslClient.GetCustomFieldService().GetCustomFields(Direction.ASCENDING);

// Get the first custom field from the account
CustomField retrieveCustomField = eslClient.GetCustomFieldService().GetCustomField(customFieldId1);

    Deleting a Custom Field

    Deleting a custom field from your account is also done with the OneSpan Sign CustomFieldService. The following code will do this:

    // Delete the second custom field from the account
eslClient.GetCustomFieldService().DeleteCustomField(customFieldId1);

    Editing a Signature Block to Add Custom Fields

    To edit signature block to add custom codes, use the following code. In this example, text anchors are used to position both signature and custom fields. For more information, see Text Anchors.

    .WithSignature(SignatureBuilder.SignatureFor(email1)
    .WithPositionAnchor(TextAnchorBuilder.NewTextAnchor("Client Signature")
        .AtPosition(TextAnchorPosition.TOPLEFT)
        .WithOccurrence(0)
        .WithCharacter(16)
        .WithSize(250, 70)
        .WithOffset(20, -58))
    .WithField(FieldBuilder.CustomField(customField.Id)
        .WithPositionAnchor(TextAnchorBuilder.NewTextAnchor("Policy Number")
            .AtPosition(TextAnchorPosition.TOPLEFT)
            .WithOccurrence(0)
            .WithCharacter(13)
            .WithSize(250, 25)
            .WithOffset(20, -10))))

    Results

    Once you have run your code, you will find your custom fields can be seen in your OneSpan Sign account. These custom fields will also be available for use in transactions. For more information, see Custom Fields.

    REST API

    To download the full code sample see our Code Share site.

    A Custom Field is one that, at the time of signing, is automatically populated with data that is specific to the signer. For instance, a signer might have an Agent Number, and that number may need to appear in the final document next to their signature. By using a custom field, the signer can specify their Agent Number, and that number will automatically appear in any other field that has been configured to receive it.

    The Custom Fields page enables you to manage the custom fields in your account.

    This functionality is available only if custom fields are enabled at the account level. Please contact our Support Team to have them enabled.

    Creating a Custom Field

    Every custom field you create is identified by the unique id you set during this process. In the JSON below, the value object is the value that appears after your signer has signed the document. This field is required when creating a custom field.

    Creating another custom field with the same id will overwrite the original custom field. Also, note that every custom field you create is done so for the entire account.

    To create a custom field, you will need to make the following request:

    HTTP Request

    POST /api/account/customfields

    HTTP Headers

    Accept: application/json   
Content-Type: application/json   
Authorization: Basic api_key

    Request Payload

    {
  "id": "policy_number_id",
  "value": "123-456-789-0",
  "required": false,
  "translations": [
    {
      "language": "en",
      "name": "Policy Number",
      "description": "Car Insurance Policy Number."
    }
  ]
}

    For a complete description of each field, see the Request Payload table below.

    Response Payload

    {
  "dirtyFields": [
    "translations",
    "id",
    "value",
    "required"
  ],
  "required": false,
  "id": "policy_number_id",
  "data": null,
  "translations": [
    {
      "dirtyFields": [
        "name",
        "description",
        "language"
      ],
      "description": "Car Insurance Policy Number.",
      "language": "en",
      "id": "",
      "data": null,
      "name": "Policy Number"
    }
  ],
  "value": "123-456-789-0",
  "name": ""
}

    Custom fields also contain a collection of translations which are used when displaying the custom field to account members.

    This tip is for accounts that support multiple languages. As a best practice, every custom field you need should be replicated for every language supported in your account. The system will only display the custom field in the language selected by the active user. If a custom field is not mapped to a language, it will default to English, regardless of the language selected by the active user.

    Retrieving Custom Fields

    You can either retrieve all your custom fields by making a GET request to:

    https://sandbox.esignlive.com/api/account/customfields.

    Or, you can retrieve a specific custom fields by using it's custom ID in your GET request:

    https://sandbox.esignlive.com/api/account/customfields/{customFieldId}

    Deleting a Custom Field

    Deleting a custom field from your account is done by making a DELETE request to:

    https://sandbox.esignlive.com/api/account/customfields/{customFieldId}

    Editing a Signature Block to Add Custom Fields

    To edit signature block to add custom codes, use the following code. In this example, text anchors are used to position both signature and custom fields. For more information, see Text Anchors.

    {
  "approvals": [
    {
      "fields": [
        {
          "type": "SIGNATURE",
          "extract": true,
          "extractAnchor": {
            "text": "Client Signature",
            "index": 0,
            "width": 250,
            "height": 70,
            "anchorPoint": "TOPLEFT",
            "characterIndex": 16,
            "leftOffset": 20,
            "topOffset": -58
          },
          "subtype": "FULLNAME"
        },
        {
          "type": "INPUT",
          "extract": true,
          "extractAnchor": {
            "text": "Policy Number",
            "index": 0,
            "width": 250,
            "height": 25,
            "anchorPoint": "TOPLEFT",
            "characterIndex": 13,
            "leftOffset": 20,
            "topOffset": -10
          },
          "subtype": "CUSTOMFIELD",
          "name": "policy_number_id"
        }
      ],
      "role": "Signer1"
    },
    {
      "fields": [
        {
          "type": "SIGNATURE",
          "extract": true,
          "extractAnchor": {
            "text": "Manager Signature",
            "width": 250,
            "height": 70,
            "index": 0,
            "anchorPoint": "TOPLEFT",
            "characterIndex": 17,
            "leftOffset": 20,
            "topOffset": -58
          },
          "subtype": "FULLNAME"
        },
        {
          "type": "INPUT",
          "top": 50,
          "left": 50,
          "height": 50,
          "width": 250,
          "subtype": "CUSTOMFIELD",
          "name": "agent_number_id"
        }
      ],
      "role": "Signer2"
    }
  ]
}

    Results

    Once you have run your code, you will find your custom fields can be seen in your OneSpan Sign account. These custom fields will also be available for use in transactions. For more information, see Custom Fields.

    Request Payload Table

    Property

    Type

    Editable

    Required

    Default

    Sample Values

    id

    string

    yes

    no

    n/a

    policy_number_id

    value

    string

    yes

    no

    n/a

    123-456-789-0

    required

    boolean

    yes

    no

    false

    false / true

    translations

    language

    string

    yes

    no

    en

    en / fr / es ...

    name

    string

    yes

    no

    n/a

    Policy Number

    description

    string

    yes

    no

    n/a

    Car Insurance Policy Number

    Was this article helpful?
    What's Next
    Change password!
    Changing your password will log you out immediately. Use the new password to log back in.
    Change profile
    Success!
    First name must have atleast 2 characters. Numbers and special characters are not allowed.
    Last name must have atleast 1 characters. Numbers and special characters are not allowed.
    Enter a valid email
    Enter a valid password
    Your profile has been successfully updated.
    Logout
    ESC

    Ozzy, our interactive help assistant