Upload and name a file

Tip: Interface patterns give you an opportunity to explore different interface designs. Be sure to check out How to Adapt a Pattern for Your Application.

Goal

Allow users to upload and name a file.

This design pattern is not recommended for offline interfaces because reflecting immediate changes in an interface based on user interaction requires a connection to the server.

images/edit-document-details-before-submitting.gif

This scenario demonstrates:

How to configure a file upload component to upload a document and store it in the folder for a document management record type. In most cases, documents are created alongside other application data, but for this recipe, we are uploading a document without other application data.
How to use the document() function to view and edit document properties before submitting.

Rule inputs

This expression includes a rule input (ri!record) set to the AR Order Document record type, which is a document management record type.

Rule Input Name	Type	Description
`record`	AR Order Document record type, which is a document management record type.	Stores the document identifier for the uploaded document. The AR Order Document has a many-to-one relationship with the Document record type, so we can also reference and update information from that record type.
`cancel`	Boolean	Stores true or false to indicate if the action was canceled.

Expression

a!formLayout(
  titleBar: a!headerTemplateFull(
    title: "Upload a Document",
    secondaryText: "Edit the file name and description before submitting",
  ),
  isTitleBarFixed: true,
  contents: {
    a!cardLayout(
      contents: {
        a!localVariables(
        /* By default, document properties are hidden when a user uploads a document */
          local!expandDetails: false,
          a!sectionLayout(
            label: "Document",
            labelSize: "EXTRA_SMALL",
            labelColor: "STANDARD",
            contents: a!cardLayout(
              contents: {
                a!sideBySideLayout(
                  items: {
                    a!sideBySideItem(
                      item: a!fileUploadField(
                        label: "Document",
                        labelPosition: "ABOVE",
                        target: recordType!AR Order Document,
                        maxSelections: 1,
                        required: true,
                        value: ri!record[recordType!AR Order Document.fields.documentId],
                        saveInto: {
                          ri!record[recordType!AR Order Document.fields.documentId],
                        /* If the user updates the name, save the value */
                          a!save(
                            ri!record[recordType!AR Order Document.relationships.documentProperties.fields.name], 
                            document(ri!record[recordType!AR Order Document.fields.documentId], "name")),
                        /* If the user adds a description, save the value */
                          a!save(
                            ri!record[recordType!AR Order Document.relationships.documentProperties.fields.description], 
                            document(ri!record[recordType!AR Order Document.fields.documentId], "description"))
                        },
                        fileNames: ri!record[recordType!AR Order Document.relationships.documentProperties.fields.name],
                        fileDescriptions: ri!record[recordType!AR Order Document.relationships.documentProperties.fields.description],
                        marginBelow: "NONE"
                      )
                    ),
                    /* Allow users to remove the uploaded document */
                    a!sideBySideItem(
                      showWhen: a!isNotNullOrEmpty(ri!record[recordType!AR Order Document.fields.documentId]),
                      item: a!imageField(
                        size: "ICON",
                        images: a!documentImage(
                          document: a!iconIndicator(
                            icon: "REMOVE"
                          ),
                          altText: "Remove Document",
                          link: a!dynamicLink(
                            saveInto: {
                              a!save(ri!record[recordType!AR Order Document.fields.documentId], null()),
                              a!save(local!expandDetails, false()),

                            }
                          )
                        )
                      ),
                      width: "MINIMIZE"
                    )
                  },
                  alignVertical: "MIDDLE",
                  spacing: "STANDARD",
                  marginBelow: "NONE"
                ),
		/* Section to show or hide the document name and description */
                a!sectionLayout(
                  showWhen: a!isNotNullOrEmpty(ri!record[recordType!AR Order Document.fields.documentId]),
                  contents: a!richTextDisplayField(
                    accessibilityText: if(local!expandDetails, "Hide document properties", "View and edit document properties"),
                    labelPosition: "COLLAPSED",
                    value: {
                      a!richTextIcon(
                        icon: if(local!expandDetails, "angle-down-bold", "angle-right-bold"),
                        link: a!dynamicLink(
                          saveInto: a!save(local!expandDetails, not(local!expandDetails))
                        ),
                        linkStyle: "STANDALONE",
                        color: "SECONDARY",
                        size: "SMALL"
                      ),
                      a!richTextItem(
                        text: " "
                      ),
                      a!richTextItem(
                        text: "Properties",
                        link: a!dynamicLink(
                          value: true,
                          saveInto: a!save(local!expandDetails, not(local!expandDetails))
                        ),
                        linkStyle: "STANDALONE",
                        color: "#636363",
                        size: "STANDARD",
                        style: "PLAIN"
                      )
                    },
                    marginBelow: if(local!expandDetails, "STANDARD", "NONE")
                  ),
                  divider: "ABOVE",
                  marginBelow: "LESS"
                ),
                a!columnsLayout(
                  columns: {
                    a!columnLayout(
                      contents: {
                        a!textField(
                          label: "Name",
                          required: true,
                          value: ri!record[recordType!AR Order Document.relationships.documentProperties.fields.name],
                          saveInto: ri!record[recordType!AR Order Document.relationships.documentProperties.fields.name],

                        ),
                        a!paragraphField(
                          label: "Description",
                          value: ri!record[recordType!AR Order Document.relationships.documentProperties.fields.description],
                          saveInto: ri!record[recordType!AR Order Document.relationships.documentProperties.fields.description],

                        )
                      },
                      width: "MEDIUM_PLUS"
                    )
                  },
                  showWhen: local!expandDetails,
                  marginBelow: "NONE"
                )
              },
              padding: if(a!isNullOrEmpty(ri!record[recordType!AR Order Document.fields.documentId]), "NONE", "STANDARD"),
              showBorder: a!isNotNullOrEmpty(ri!record[recordType!AR Order Document.fields.documentId])
            )
          )
        ),
      },
      shape: "SEMI_ROUNDED",
      padding: "MORE",
      style: "NONE"
    )
  },
  buttons: a!buttonLayout(
    primaryButtons: {
      a!buttonWidget(
        label: "Submit",
        /* If you don't use this interface in a start form or task, */
        /* replace submit: true with saveInto: a!submitUploadedFiles() */
        submit: true,
        validate: true,
        style: "SOLID"
      )
    },
    secondaryButtons: {
      a!buttonWidget(
        label: "Cancel",
        submit: true,
        validate: false,
        saveInto: ri!cancel,
        style: "OUTLINE",
        value: true
      )
    }
  ),
  backgroundColor: "#F6F7F9",
  showTitleBarDivider: false,
  contentsWidth: "FULL"
)

Test it out

Record type references are specific to each environment. If you copy and paste the expression above into an interface, it will not evaluate.

To test this expression in your application:

Create an interface.
Create the necessary rule inputs.
Copy and paste the expression in the interface.
Replace all record type references with references to the document management record type in your environment.

Notable implementation details

If you want to upload files outside of a start form or task, update the saveInto parameter in the Submit button to saveInto: a!submitUploadedFiles().
If you want to allow users to upload multiple files in a start form or task, see either of the following recipes:
- Upload Multiple Documents in an Editable Grid.
- Upload Multiple Documents and Edit Document Properties.
To allow users to preview an uploaded file, you can add a document viewer component within the section that shows or hides the document details.

Feedback

Was this page helpful?