SimpleOne supports attaching files to existing or newly created records such as incidents, change requests, and some others.  

The files can be attached in two ways:

Attachment action 


You can attach files to a field of image type and a record with the attachment action. It is displayed on forms as the paper clip icon .

The picture below illustrates two attachment actions on the record form:

Operate the attachments using the SimpleAttachment API methods.

Attachment widget 


Attachments can be added via an attachment widget in the agent interface. For this, you need to use the <attachment> SimpleTag within a certain widget instance. It is unnecessary to specify the recordId, tableName attributes for the <attachment> tag located on the page with the form. Therefore, a widget template with an attachment tag will look like this:

<attachment> </attachment> 

After adding a widget instance on a form of the agent interface, the standard action in the top right corner of the form will be removed:

You can add files from the clipboard to the widget directly on the form by using Ctrl+V shortcut while hovering over Drag & drop area.

Add and manage attachments


You can attach files in the following ways:

  • Drag files into the window.
  • Click Upload from computer and add files via the file manager.
  • Copy and paste files from the file manager.

Upload a file


To attach a file to some record, complete the steps below:

  1. Navigate to a record you need to work on.

  2. Open the Attachments window:

    • Click the attachments icon at the top right corner.

    • Click the attachments icon by the field name.

  3. Attach the file you need. Attached files appear at the top of the form or by the field name.

  4. Close the Attachments window to return to the record.

  5. Click Save or Save and Exit.

When uploading a file via the attachments icon at the top right corner, you do not need to save the record. Attached files are saved on the server automatically.

The picture below illustrates the attachment window:

Copy a file


To copy attachments, use the server-side scripts. You can use one of the following ways:

  • Use the base64 object of the original attachment. Due to the specifics of the readBase64 method, the maximum size of the copied file is 10 Mb.

    Example
    const attachmentRec = new SimpleRecord('sys_attachment');
    attachmentRec.get('167654133500015741');
    ss.info(`Original size bytes: ${attachmentRec.size_bytes}`);
    // Info: Original size bytes: 92414492
      
    const attach = new SimpleAttachment();
    const base64Value = attach.readBase64(attachmentRec.sys_id);
      
    const attachCopyId = attach.writeBase64(
      attachmentRec.record_document_id,
      'copy_of_' + attachmentRec.file_name,
      base64Value,
      attachmentRec.mime_content_type
    );
    if (attachCopyId) {
      attachmentRec.get(attachCopyId);
      ss.info(`/record/sys_attachment/${attachCopyId}`);
      // Info: /record/sys_attachment/167654428100399185
      ss.info(`Copy size bytes: ${attachmentRec.size_bytes}`);
      // Info: Copy size bytes: 0
    }
  • Use the SimpleAttachmentService class. The maximum size of the copied file depends on the instance-wide limit that is specified in the max_file_size_upload system property.

    Example
    const attachmentRec = new SimpleRecord('sys_attachment');
    attachmentRec.get('167654133500015741');
    ss.info(`Original size bytes: ${attachmentRec.size_bytes}`);
    // Info: Original size bytes: 92414492
      
    const importSource = new SimpleRecord('sys_import_source');
    importSource.get('167647710807446665'); // From Incident Import Source
    const docId = ss.getDocIdByIds(importSource.sys_db_table_id, importSource.sys_id);
      
    const attach = new SimpleAttachment();
    const attachUrl = attach.getAttachmentUrlById(attachmentRec.sys_id);
    const simpleAttach = new SimpleAttachmentService();
    const docID = ss.getDocIdByIds(importSource.sys_db_table_id, importSource.sys_id);
    const attachCopyId = simpleAttach.createAttachmentByUrl(attachUrl, docId, `Copy_of_the_${attachmentRec.file_name}`);
      
    if (attachCopyId) {
      attachmentRec.get(attachCopyId);
      ss.info(`/record/sys_attachment/${attachCopyId}`);
      // Info: /record/sys_attachment/167654472004676912
      ss.info(`Copy size bytes: ${attachmentRec.size_bytes}`);
      // Info: Copy size bytes: 92414492
    }

Delete a file


To delete a file uploaded earlier, complete the steps below:

  1. Navigate to a record you need to work on.

  2. Open the Attachments window:

    • Click the attachments icon in the top right corner.

    • Click the attachments icon by the field name.

  3. Delete a file or files in the following ways: 

      • If there is one file, click Delete.

      • If there are multiple files:

        • To delete a single file, move the pointer to the file and click the delete icon .
        • To delete some files, move the pointer to a file you need to delete, click the three-dots icon , and then select Choose. Repeat for other files you need to delete. Click Delete (x).
        • To delete all files, click Select all and Delete (x).

  4. Close the Attachments window to return to the record.

  5. Click Save or Save and Exit.

When deleting a file via the attachments icon in the top right corner, you do not need to save the record. Attached files are saved on the server automatically.

Parsing and indexing


Attachment content parsing and indexing are possible only if the attachment file size is under 30 Mb. The limit is fixed and cannot be modified. If the file is bigger than 30 Mb, it will not be indexed. The warning message related to the indexation will be written to logs. The log message will be the following: Attachment {Attachment ID} content parsing failed.

You will be able to find more information later in the Main Log (sys_log) table using the criteria below for the filter:

    • Source IS Attachment Parser

    • Message Contains { Attachment ID }

Indexing is performed only for specific file formats. The Content field will be automatically filled with the text content of the attached file if the file extension is included in the list: 'txt', 'ini', 'reg', 'csv', 'json', 'htm', 'html', 'doc' , 'docx', 'xls', 'xlsx'.  Full Text Search is enabled within the Content field. It allows you to search globally for its content.

The attachment parsing and indexing process is asynchronous. Within this process, the events below are implemented:

  1. Some file is attached to a record to any table (for example, to a record 164313550512027919 in the Task table).

  2. After that, a search index for this attachment is created. Technically, it is a record in the Search Indices (sys_search_index) with the fields populated like shown below:

    Field

    Type

    Value

    Record

    Big Integer

    164313646211541086

    Table

    Reference

    Attachment

    Column

    Reference

    Content

    Text

    Text

    In this field, the attachment content appears.

  3. In the Attachments (sys_attachment) table record, the attachment content parsed from the provided file is placed. The attachment content is populated in the Content field, and the content encoding to the Encoding field. The content encoding is automatically detected.

Attachment Download URL


Attachment records can be public or non-public. The publicity of attachments affects whether an attachment link will have an expiration date.

  • Links to public attachments do not expire.
  • Links to non-public attachments have a lifetime of 1 hour by default from the moment they are generated. The lifetime of a link is determined through the system property s3.presigned.link.lifetime.

The Is Public attribute on the Attachment form defines the publicity of attachments. 

There are two ways of generating attachment links:

  1. If you are logged in, use the relative link `/attachments/${sys_attachment.sys_id}` to download attachments. 
  2. Generate a link like `{your-instance-url}/v1/attachments/download/{sys_attachment.sys_id}?access-token={s_user.accessToken}`, where 
    • your-instance-url – the address of the instance where the attachment resides. If the attachment in on the same instance that the script is running on, use a relative link `/v1/attachments/download/${sys_attachment.sys_id}?access-token=${s_user.accessToken}`.
    • sys_attachment.sys_id – Attachment ID.
    • user_token – user token. To get the current user's token in the client script, use the s_user.accessToken property. To get the current user token in the server script, use the getAccessToken() method of the SimpleUser() class.
  3. Use the getAttachmentUrlById() Server API method to get the link. 

    Example
    const current = new SimpleRecord('sys_attachment');
    current.get('164313646211541086');
    const ATTACH_ID = current.sys_id;
    
    const simpleAttach = new SimpleAttachment();
    const attachUrl = simpleAttach.getAttachmentUrlById(ATTACH_ID);

    Depending on the publicity of an attachment, two links will be generated. For example:

      • for non-public attachments: https://s3-{your-instance-url}/attachment/9/b7/prp5bikeyg70mpn7mhfszi4amgzleo?response-content-disposition=inline%3B%20filename%3D%22image.png%22&response-content-type=image%2Fpng%3B&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Algorithm=...&X-Amz-Credential=...&X-Amz-Date=...&X-Amz-SignedHeaders=host&X-Amz-Expires=3600&X-Amz-Signature=...
      • for public attachments: https://s3-{your-instance-url}/public-attachment/9/b7/prp5bikeyg70mpn7mhfszi4amgzleo?response-content-disposition=inline%3B%20filename%3D%22image.png%22&response-content-type=image%2Fpng%3B