Secure Attachments

Secure Attachments

Secure Attachments is an extension of the Propeller Platform Media offering that allows you to securely store and manage attachment files in Propeller Commerce. You can use Secure Attachments to upload, store, and retrieve attachments such as PDF, Excel documents or ZIP archives. This feature provides a secure and reliable way to manage attachments associated with Orders and SparePartMachines, and potentially other entities in the future.

Why It's Important

Propeller Commerce allows businesses to associate attachments with various entities such as Orders, Machines&SpareParts, and more. Secure Attachments ensure that files are stored securely and can only be accessed and downloaded by authorized users. This feature provides a secure and reliable way to manage attachments, ensuring that sensitive information is protected and that files are stored safely.

Note: Evert attachment to belong to only one type (e.g. Order) and can be associated with ether single Customer or one or more Companies

Key Topics Covered

• Secure Attachments Architecture: Overview of the architecture of Secure Attachments
• Roles and Permissions: How roles and permission rules are applied to Secure Attachments
• Attachments Operations: Available operations with attachments
  1. Creating Attachments: How to create attachments
  2. Updating Attachments: How to download attachments
  3. Deleting Attachments: How to delete attachments
  4. Getting Single Attachment: How to retrieve attachment(s)
  5. Listing & Filtering Attachments: How to list attachments
  6. Downloading Attachments: How to download attachments

Secure Attachments Architecture

Secure Attachments are stored in a secure and reliable way using the Attachment entity. The Attachment entity is associated with other entities such as Orders and SparePartMachines using a OneToOne relationship. This ensures that attachments are securely stored and can only be accessed by authorized users.

Roles and Permissions

Role&Permission rules are applied to Secure Attachments to ensure that only authorized users can access and manage attachments.

The following roles and permissions are available for Secure Attachments:

1. Admin: Admin users have full access to Secure Attachments and can perform all operations.
2. Contact: Contacts have access to their own attachments and can perform read and write operations to the attachments associated with the company they belong to and the orders they are associated with.
3. Company: All contacts belonging to an Company have access to the attachments and can perform read and write operations.
4. Customer: Customers have access to their own attachments and can perform full operations on the attachments associated with their orders.
5. Anonymous: Anonymous users have no access to Secure Attachments and cannot view or manage attachments.

Note: The permissions for your user are securely store into the JWT token and are used to determine the access level of the particular user. In order for the permissions to be applied, the user must be authenticated. In case the user is not authenticated you will get 403 Forbidden response.

For integration purposes with Propeller Commerce and your ERP or other systems we suggest that you create dedicated Admin, or dedicated Company user that will be used for the integration purposes and manage the attachments on behalf of the your users.

Attachment Operations

The following standard GraphQL operations are available with Secure Attachments:

Creating Attachments

You can create attachments by uploading files to Propeller Commerce. Attachments can be associated with entities such as Orders and SparePartMachines.

Example create an attachment mutation:

mutation AttachmentCreate($input: MediaAttachmentInput!) {
  mediaAttachmentCreate(input: $input) {
    id    
    # you can retrieve all the available fields for the attachment entity...
  }
}

Example input variables:

{
  "input": {
    "alt": [
      {
        "language": "EN",
        "value": "Example English Alt"
      }
    ],
    "description": [
      {
        "language": "EN",
        "value": "Example English Desc."
      }
    ],
    "tags": [
      {
        "language": "EN",
        "values": [
          "eg. tag1",
          "eg. tag2"
        ]
      }
    ],
    "companyId": 42,
    "orderId": 42,
    "uploadAttachments": [
      {
        "language": "EN",
        "uploadType": "URL",
        "urlFile": {
          "fileName": "example-attachment.pdf",
          "url": "https://example-upload.com/example-order.pdf"
        }
      },
      {
        "language": "EN",
        "uploadType": "BASE64",
        "base64File": {
          "fileName": "example-attachment.pdf",
          "base64": "JVBERi0xLjQNCiWhs8XXDQoxIDAgb2JqDQo8PC9DcmVhdGlvbkRhdGUoRDoyMDI0MTEwMTE1MzI1NSswMCcwMCcpL0NyZWF0b3IoSXJvblBkZikvTW9kRGF0ZShEOjIwMjQxMTAxMTUzMjU1KzAwJzAwJykvUHJvZHVjZXIoSXJvblBkZiB2MjAyMy41LjEzOTQ1KT4..."
        }
      },
      {
        "language": "EN",
        "uploadType": "FILE",
        "file": {
          "fileName": "example-attachment.pdf",
          "file": null
        }
      }
    ]
  }
}

The example variables payload above contains most of the available fields for the MediaAttachment type. For uploading attachments you can use one of the following upload types:

• URL - for uploading attachments from the URL
• BASE64 - for uploading attachments from a base64 string
• FILE - for uploading attachments from a file ( for the file upload please refer to the graphql-upload standard )

Please refer to the [MediaAttachmentInput] input type for all the available fields for the create mutation.

Updating Attachments

You can update attachments by modifying the attachment fields in Propeller Commerce. This allows you to update the attachment metadata such as the alt, description, and tags fields etc.

Example update an attachment mutation:

mutation AttachmentUpdate($input: UpdateMediaAttachmentInput!) {
  mediaAttachmentUpdate(input: $input) {
    id    
    # you can retrieve all the available fields for the attachment entity...
  }
}

Example input variables:

{
  "input": {
    "id": 42,
    "alt": [
      {
        "language": "EN",
        "value": "Example English Alt"
      }
    ],
    "description": [
      {
        "language": "EN",
        "value": "Example English Desc."
      }
    ],
    "tags": [
      {
        "language": "EN",
        "values": [
          "eg. tag1",
          "eg. tag2"
        ]
      }
    ]
  }
}

Please refer to the UpdateMediaAttachmentInput input type for all the available fields for the update mutation.

Deleting Attachments

You can delete attachments by removing the attachment from Propeller Commerce with an GQL mutation. This will remove the attachment file from the system.

Example delete an attachment mutation:

mutation AttachmentDelete($id: ID!) {
  mediaAttachmentDelete(id: $id)   
}

Example input variables:

{
  "id": 42
}

Getting Single Attachment

You can retrieve a single attachment by querying the attachment by its id in Propeller Commerce.

Example get a single attachment query:

query GetSingleAttachment($id: String!) {
  media {
    attachment(id: $id) {
      id
      attachments {
        language
        mimeType
        originalUrl
      }
      # you can retrieve all the available fields for the attachment entity...
    }
  }
}

Example input variables:

{
  "id": "42"
}

Listing & Filtering Attachments

You can list and filter attachments by querying the attachments in Propeller Commerce. This allows you to retrieve a list of attachments associated with entities such as Order and specific Company only.

For all the available filtering options please refer to the MediaAttachmentSearchInput input type.

Example list attachments query:

query ListAndFilterAttachments($input: MediaAttachmentSearchInput) {
  media {
    attachments(input: $input) {
      items {
        id
        attachments {
          language
          mimeType
          originalUrl
        }
      }
      itemsFound
      offset
      page
      pages
      start
      end
    }
  }
}

Example input variables:

{
  "input": {
    "orderId": 42,
    "companyId": 42
  }
}

Please refer to the MediaAttachmentSearchInput input type for all the available fields for the list query.

Please refer to the MediaAttachment type for all the available fields for the attachment entity.

Downloading Attachments

You can download (render/display) attachments from Propeller Commerce by making an GET request to the provided originalUrl link associated with the attachment. This allows you to access and view the attachment file.

Note: To view the attachment file you must be authenticated and have the necessary permissions to access the attachment.

Example download an attachment request with authentication headers:

curl -X GET https://firebasestorage.googleapis.com/v0/b/staging.attachments.helice.cloud/o/example-tenant%2Forders%2F42%2Fcompanies%2F42%2Fen%2Fxxxxxxxx-yyyy-zzzz-kkkk-llllllllllll-example-attachment.pdf?alt=media \
  -H "Authorization: Bearer <JWT>"

Please note the url from the example above, the originalUrl is the link to the attachment file and always will be in the following format:

https://firebasestorage.googleapis.com/v0/b/<bucket>/o/<path-to-the-file>?alt=media