Authorization Link

Function: a!authorizationLink()

Defines a link to authorize a user for a connected system that uses the OAuth 2.0 Authorization Code grant. Links can be used in charts, grids, hierarchy browsers, images, link fields, milestones, pickers, and rich text.

See Also: OAuth 2.0: Authorization Code Grant, Link, Read-Only Grid, Images

Parameters

Name Keyword Types Description

Label

label

Text

Text displayed as the link name the user clicks on.

Connected System

connectedSystem

Connected System

Connected system used to generate the authorization link. Provide the connected system value returned by an integration when the response indicates that the user needs to authorize.

Visibility

showWhen

Boolean

Determines whether the component is displayed on the interface. When set to false, the component is hidden and is not evaluated. Default: true.

Usage considerations

Authorizing users & getting data

  • Be sure to read through the external system's documentation to understand what is returned when the user needs to authorize or reauthorize
  • For integrations getting data, use dot notation. For integrations writing data use fv!connectedSystem.
  • If the mobile user is signed in as one user in the mobile browser and a different user in the mobile app, authorization will fail.
  • A link created by a!authorizationLink() opens in a new browser window.
  • For mobile, a link created by a!authorizationLink() will open the device's default browser
    • Authorization links are made for mobile, so you don't need to worry about the user not being signed-in in the mobile browser.

Examples

When connecting with OAuth, integrations can either get data from or post data to another system

Integrations retrieving data

Assuming that the integration used a custom error message that returned Access_token when an access token was missing, the following interface expression will provide an authorization link.

1
2
3
4
5
6
7
8
9
10
11
12
a!localVariables(
  local!integrationResult: rule!EXAMPLE_OAuthIntegration(),
  a!linkField(
    label: "Example Authorization Link",
    /* show when */
    showWhen: local!integrationResult.error.message = "Access_token",
    links: a!authorizationLink(
      label: "Authorize",
      connectedSystem: local!integrationResult.connectedSystem
    )
  )
)

Integrations writing data

If the integration is writing data to another system via OAuth, the integration would be called as a result of a save. These types of integrations, by default, return onSuccess and onError. fv!connectedSystem is returned when there's an error and can be retrieved through the onError parameter and used to populate the authorization link field.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
a!localVariables(
  local!results,
  local!connectedSystem,
  local!verify,
  a!sectionLayout(
    contents: a!columnsLayout(
      columns: {
        a!columnLayout(
          contents: {
            a!buttonLayout(
              secondaryButtons: {
                a!buttonWidget(
                  label: "Save Changes",
                  saveInto: {
                    a!save( local!verify, true),
                    rule!EXAMPLE_OAuthIntegration(
                      onSuccess: a!save( local!results, fv!result),
                      onError: a!save( local!connectedSystem, fv!connectedSystem)
                    )
                  }
                )
              }
            ),
            a!linkField(
              label: "Authorization After Write Attempt",
              showWhen: and(not(isnull(local!connectedSystem)), not(isnull(local!verify))),
              links: a!authorizationLink(
                label: "Authorize",
                connectedSystem: local!connectedSystem
              )
            )
          }
        )
      }
    )
  )
)
Open in Github Built: Thu, Feb 23, 2023 (02:59:22 PM)

On This Page

FEEDBACK